🦜 Welcome! This repository contains the documentation build pipeline for LangChain projects.
- 🏠
docs.langchain.comis 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.comis home to the API reference docs for LangChain, LangGraph, LangSmith, and LangChain integration packages (e.g.,langchain-anthropic,langchain-openai). These are static sites built from the source code and deployed to Vercel.
Important
The LangSmith API and SDK references are not yet fully consolidated to this repo. Visit their documentation:
Table of contents:
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.
Important
For contributing to reference docs, see the README.md file in the /reference/python and /reference/javascript directories.
# --- docs.langchain.com ----------------------------------------------
build/ # Built docs (DO NOT EDIT)
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
# --- 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
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.
Important
Never edit /build directly.
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.
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.
- 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 rebuildmake build- Build documentation to./builddirectorymake 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 docsmake preview-references- Preview reference docs using vercelmake install- Install all dependenciesmake clean- Remove build artifactsmake test- Run the test suitemake lint- Check code style and formattingmake format- Auto-format codemake lint_md- Lint markdown filesmake lint_md_fix- Lint and fix markdown filesmake 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,.ipynbfiles
-
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,.ipynbfiles - 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/tobuild/ - 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
- Automatically rebuilds changed files from
-
docs build- Build documentation files--watch- Watch for file changes after building
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 nameRoot 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):
-
Use the safe Make commands (recommended):
make mint-broken-links # Builds docs first, then checks links (excludes integrations) -
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.
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
