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

• 🏠 docs.langchain.com is our docs home, centralizing LangChain, LangGraph, LangSmith, and LangChain Labs (Deep Agents, Open SWE, Open Agent Platform). This site is hosted on Mintlify.
• 🛠️ reference.langchain.com hosts generated API reference for LangChain, LangGraph, LangSmith, and integration packages. That site is not built from this repository (no reference build scripts or output live here).
  • Python reference
  • JavaScript/TypeScript reference
• 💬 chat.langchain.com is an AI-powered assistant that can answer questions about LangChain documentation.

Table of contents:

• LangChain Docs
  • Contribute
  • Reference
    • Repository structure
      • docs.langchain.com
      • reference.langchain.com
    • File formats
    • Available commands
  • Linting
    • Codespell
  • Troubleshooting
    • docs dev not working / running
    • Mintlify .venv parsing error
    • Warning: page doesn't exist
    • General Mintlify errors

To run a local preview of the documentation:

git clone https://github.com/langchain-ai/docs.git

cd docs

make install

make dev

For more information on how to contribute to LangChain documentation, follow the steps outlined in the contributing guide. The contributing guide also explains our documentation types and their writing and quality standards.

For detailed information about setting up your development environment and contributing to documentation, see the documentation contributing guide.

To report issues with reference.langchain.com (missing pages, broken links, or generated API content), open a reference documentation issue on this repo so maintainers can route it.

# --- docs.langchain.com ----------------------------------------------
build/                    # Built docs (DO NOT EDIT)
packages.yml              # Package metadata (indexes, tables, downloads; not the API reference build)
pipeline/                 # Build pipeline source code
scripts/                  # Helper scripts
src/                      # Source documentation files (< EDIT CONTENT HERE)
    langsmith/            # LangSmith docs
    oss/                  # LangChain, LangGraph, Deep Agents, and integrations docs
    docs.json             # Mintlify site configuration and navigation
tests/                    # Test files for the pipeline
Makefile                  # Build targets
pyproject.toml            # Dependencies

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.

The /src/docs.json file is used to configure the Mintlify site navigation and settings. Refer to the Mintlify documentation for detailed syntax and component usage.

Documentation changes follow a PR workflow where all tests must pass before merging. See the contributing guidelines for more details.

API reference is generated and deployed outside this repo. Browse Python and JavaScript/TypeScript reference there. If something is wrong with that site, use the reference docs issue template.

• Markdown files (.md, .mdx) - Standard documentation content
• Snippets (src/snippets/) - Reusable MDX content that can be imported into multiple pages. Important: Snippets undergo special link preprocessing. When writing links in snippets, be careful about path segments.
• Jupyter notebooks (.ipynb) - Converted to markdown during build, though these are not recommended for new content! Your PR will likely be rejected if you attempt to add a Jupyter notebook unless asked to by a maintainer.
• Assets - Images and other files are copied to the build directory

Make commands:

• make dev - Start development mode with file watching and live rebuild
• make build - Build documentation to ./build directory
• make broken-links - Check for broken links in documentation
• make broken-links-with-anchors - Check for broken links + check links with anchors
• 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

After running make install, you can use make lint_prose to ensure your writing meets our style guide rules.

make lint runs uv run codespell src to check source documentation for common spelling errors.

Codespell is configured in pyproject.toml under [tool.codespell]:

• Add custom accepted words to src/.codespellignore. This file is referenced by ignore-words = "src/.codespellignore".
• Exclude generated files, vendor content, or other paths that should not be spell checked by adding glob patterns to the skip setting.
• Keep skip patterns scoped. Prefer adding accepted words to src/.codespellignore when the word is valid documentation content, and use skip when the file or directory should not be checked at all.

You can also follow these steps to enable vale with VS Code or Cursor:

1. Install the Vale extension (Vale by Chris Chinchilla)
2. Install Vale CLI: brew install vale (macOS) or see Vale installation for other platforms
3. Navigate to the Vale extension settings:
   • Set Vale CLI: Config to the absolute path to .vale.ini (in the root of this repo)
   • Set Vale CLI: Min Alert Level to suggestion (many rules are coded as suggestions)

If you cannot use the VS Code UI to configure Vale, add these settings to your settings.json:

    "vale.valeCLI.config": "/path/to/docs/.vale.ini",
    "vale.valeCLI.minAlertLevel": "suggestion"

Note: The extension requires Vale on your PATH. If annotations don't appear (e.g., when Cursor is launched from the Dock), launch Cursor from a terminal so it inherits your PATH, or ensure Homebrew is in your shell profile.

In some cases, we use new features that are only available in the latest Mintlify CLI. If you encounter errors, ensure you have the latest version installed:

mint update

# or

npm install -g mint

Re-do the steps to set up your dev environment, ensuring you have activated the virtual environment and installed all dependencies.

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 broken-links-with-anchors      # Builds docs first, then checks internal links

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.

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.