Documentation Build Pipeline

This repository contains the documentation build pipeline for LangChain projects.

It converts markdown and notebook files into a format suitable for Mintlify documentation sites.

The pipeline is structured with 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 testing changes.

Directory Structure

src/                  # Source documentation files (edit these)
build/                # Generated output files (do not edit)
pipeline/             # Build pipeline source code
tests/                # Test files for the pipeline
Makefile              # Build automation

Contributing quickstart

Set up virtual environment

1. Install uv from https://docs.astral.sh/uv/

2. Create and activate virtual environment:

   cd docs
   uv venv
   source .venv/bin/activate

3. Install dependencies:

   uv sync --all-groups

4. Install Mintlify CLI:

   The docs CLI uses parts of the Mintlify CLI so you need to install that too.

   npm i -g mint

5. Use the docs CLI tool:

   After setup, 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 (on save)
• 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 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
• 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

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

Note: 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

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.