LangChain Docs

🦜 Welcome! This repository contains the documentation build pipeline for LangChain projects.

• 🏠 docs.langchain.com is our docs home, centralizing LangChain, LangGraph, LangGraph Platform, LangSmith, and LangChain Labs (Deep Agents, Open SWE, Open Agent Platform). This site is hosted on Mintlify.
• 🛠️ reference.langchain.com is home to the API reference docs for LangChain, LangGraph, LangGraph Platform, and LangChain integration packages (e.g. langchain-anthropic, langchain-openai). These are static sites built from the source code and deployed to Vercel.
  • Python reference
  • JavaScript/TypeScript reference

Important

• The LangSmith API and SDK references are not yet consolidated to this repo. Visit their documentation:
  • HTTP API Reference
  • Python SDK reference
  • JavaScript/TypeScript SDK reference

---

Overview

# --- docs.langchain.com ----------------------------------------------
build/                    # Built docs (do not edit)
pipeline/                 # Build pipeline source code
scripts/                  # Helper scripts
src/                      # Source documentation files (edit these)
    labs/                 # LangChain Labs docs
    langgraph-platform/   # LangGraph Platform docs
    langsmith/            # LangSmith docs
    oss/                  # LangChain, LangGraph, and integrations docs
    docs.json             # Mintlify site configuration
tests/                    # Test files for the pipeline
Makefile                  # Build targets
pyproject.toml            # Dependencies

# --- reference.langchain.com -----------------------------------------
reference/                # Reference docs build pipelines
    dist/                 # Build docs (do not edit)
    javascript/           # JS/TS reference build pipeline
    python/               # Python reference build pipeline and source
    package.json          # Vercel commands and dependencies
    vercel.json           # Vercel configuration/redirects

docs.langchain.com

The Mintlify docs pipeline is structured with .mdx source files in /src and build artifacts in /build. Mintlify deploys from the /build folder, which is generated by preprocessing logic - never edit /build directly.

Documentation changes follow a PR workflow where all tests must pass before merging. Publishing is handled by the publish workflow (requires authorization), and preview branches are available for sharing work-in-progress changes with others. See steps below on how to preview locally and begin contributing.

reference.langchain.com

Each language has its own build pipeline in /reference/<language>. Reference docs are built with a combination of automated docstring extraction and manually written content. Refer to the README.md in each folder for details on how to build and contribute.

Built files are stored in /reference/dist/{LANGUAGE}, which is then deployed to Vercel. The build process is triggered automatically on pushes to main and can also be triggered manually via the Vercel dashboard.

---

Contributing

The following steps refer to the docs.langchain.com Mintlify documentation site. For contributing to the reference docs, see the README.md files in /reference/python and /reference/javascript.

Set up a dev environment

1. Clone this repo. Ensure the steps in IDE_SETUP.md are followed to configure your IDE/editor to automatically apply the correct settings.

2. Install uv from https://docs.astral.sh/uv/ (if not already installed)

3. Install npm from https://nodejs.org/en/download/ (if not already installed)

4. Create and activate a virtual environment:

   cd docs
   uv venv
   source .venv/bin/activate

5. Install dependencies:

   uv sync --all-groups

   npm i -g mint

After install, you'll have access to the docs command:

docs --help

Common commands:

• docs dev - Start development mode with file watching and hot reload
• docs build - Build documentation
• docs migrate <path> - Convert MkDocs markdown files to Mintlify format
• docs migrate-docusaurus <path> - Convert Docusaurus markdown files to Mintlify format

Important rules

• Only edit files in src/ - The build/ directory is automatically generated
• Use Mintlify syntax - See Mintlify documentation for formatting guidelines
• Test your changes - Use docs dev to preview changes locally with hot reload
• Use safe Mintlify commands - Use make mint-broken-links instead of mint broken-links to check final built documentation

Available commands

Make commands

• make dev - Start development mode with file watching and live rebuild
• make build - Build documentation to ./build directory
• make mint-broken-links - Check for broken links in built documentation (excludes integrations)
• make mint-broken-links-all - Check for broken links in built documentation (includes all directories)
• make build-references - Build reference docs
• make preview-references - Preview reference docs using vercel
• make install - Install all dependencies
• make clean - Remove build artifacts
• make test - Run the test suite
• make lint - Check code style and formatting
• make format - Auto-format code
• make lint_md - Lint markdown files
• make lint_md_fix - Lint and fix markdown files
• make help - Show all available commands

docs CLI Tool

The docs command (installed as uv run docs) provides additional functionality:

• docs migrate <path> - Convert MkDocs markdown/notebook files to Mintlify format

  • --dry-run - Preview changes without writing files
  • --output <path> - Specify output location (default: in-place)
  • Supports .md, .markdown, .ipynb files

• docs migrate-docusaurus <path> - Convert Docusaurus markdown/notebook files to Mintlify format

  • --dry-run - Preview changes without writing files
  • --output <path> - Specify output location (default: in-place)
  • Supports .md, .markdown, .mdx, .ipynb files
  • Converts Docusaurus-specific syntax (admonitions, tabs, imports, etc.)

• docs mv <old_path> <new_path> - Move files and update cross-references

  • --dry-run - Preview changes without moving files

These can be used directly using the Makefile or via the docs CLI tool:

• docs dev - Start development mode with file watching and hot reload

  • Automatically rebuilds changed files from src/ to build/
  • Launches Mintlify dev server at http://localhost:3000
  • Provides automatic browser refresh when files change
  • --skip-build - Skip initial build and use existing build directory

• docs build - Build documentation files

  • --watch - Watch for file changes after building

File formats

• Markdown files (.md, .mdx) - Standard documentation content
• Jupyter notebooks (.ipynb) - Converted to markdown during build, though these are not recommended for new content!
• Assets - Images and other files are copied to the build directory

Documentation syntax

This project uses Mintlify for documentation generation. Key features:

• Frontmatter - YAML metadata at the top of files
• Components - Special Mintlify components for enhanced formatting
• Code blocks - Syntax highlighting and copy functionality
• Navigation - Automatic sidebar generation from file structure
• Code language fences (only used in /oss) - Custom code language fences for Python and Javascript (:::python and :::js). Both are closed with the ::: fence. These are used to tag content that is specific to that language and will generate two outputs (one for each language).

Refer to the Mintlify documentation for detailed syntax and component usage.

Testing

Run the test suite to ensure your changes don't break existing functionality:

make test

Code quality

Before submitting changes, ensure your code passes formatting and linting checks:

# Format code automatically
make format

# Check for linting issues
make lint

# Fix markdown issues
make lint_md_fix

Important

All pull requests are automatically checked by CI/CD.

The same linting and formatting standards will be enforced, and PRs cannot be merged if these checks fail.

---

Development workflow

First, ensure your dev environment is set up as described above and that you have followed the steps in IDE_SETUP.md to configure your IDE/editor to automatically apply the correct settings.

1. Start development mode:

   docs dev

   This starts a development server with hot reload at http://localhost:3000

2. Edit files in src/:

   • Make changes to markdown files, notebooks, or other documentation
   • The build system automatically detects changes and rebuilds affected files

3. Preview changes:

   • Changes automatically appear in your browser at http://localhost:3000
   • No manual refresh needed - the page updates automatically when you save files

4. Iterate:

   • Continue editing and see changes reflected immediately
   • The development server rebuilds only changed files for faster feedback

Create a preview build

When you create or update a PR, a preview branch/ID is automatically generated for you. A comment will be left on the PR with the ID, which you can then use to generate a preview. You can also run this workflow manually if needed.

1. Copy the preview branch's ID from the comment.
2. In the Mintlify dashboard, click Create preview deployment.
3. Enter the preview branch's ID.
4. Click Create deployment. A Manual update will display in the Previews table.
5. Select the preview and click Visit to view the preview build.

To redeploy the preview build, click Redeploy on the Mintlify dashboard.

Publish to prod

Once your branch has been merged into main, you need to push the changes to prod for them to render on the live docs site. Use the Publish documentation GH action:

1. Go to Publish documentation.
2. Click the Run workflow button.
3. Select the main branch to deploy.
4. Click Run workflow.

---

Troubleshooting

Mintlify .venv Parsing Error

Problem: Running mint broken-links or other Mintlify commands from the project root causes parsing errors like:

Unable to parse .venv/lib/python3.13/site-packages/soupsieve-2.7.dist-info/licenses/LICENSE.md
- 3:48: Unexpected character '@' (U+0040) in name

Root Cause: Mintlify tries to parse all files in the directory, including Python virtual environment files that contain invalid MDX syntax.

Solutions (in order of preference):

1. Use the safe Make commands (recommended):

   make mint-broken-links  # Builds docs first, then checks links (excludes integrations)

2. Run Mintlify commands from the build directory:

   cd build               # Change to build directory where final docs are
   mint broken-links      # Now safe to run

Why this works: The solution ensures Mintlify commands run from the build/ directory where the final documentation is generated, which is the correct place to check for broken links. This avoids scanning the Python virtual environment in the project root.

Prevention: Always use the provided Make commands instead of running raw mint commands from the project root.

Warning: page doesn't exist

If adding a new group, ensure the root index.mdx is included in the pages array like:

{
  "group": "New group",
  "pages": ["new-group/index", "new-group/other-page"]
}

If the trailing /index (no extension included) is omitted, the Mintlify parser will raise a warning even though the site will still build.