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
README.md             # This file

Contributing

Quick Start

Setup Virtual Environment (Recommended)

1. Install uv:

   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. 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
   • 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

Using Makefile (Alternative)

You can use the Makefile for easier build and development:

1. Start development mode:

   make dev

   This watches for changes in src/ and automatically rebuilds content in build/.

   This was cobbled together quickly and may not work well for all edits. If it's getting stuck, kill the process and restart it.

   Alternatively, you can make build, and launch mint inside the build/ directory to preview changes.

2. Build documentation:

   make build

   Generates compiled .mdx files in the build/ directory.

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 make dev to preview changes locally

Available Commands

Make Commands

• make dev - Start development mode with file watching and live rebuild
• make build - Build documentation to ./build directory
• 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 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

  • --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 linting:

make lint
make format

Development Workflow

1. Edit files in src/
2. Run make dev to start the development server
3. The build system will automatically detect changes and rebuild
4. Preview your changes in the generated build/ directory

Create a preview build

Once you have a PR open and are ready to preview changes, create a preview branch:

1. Go to Create a preview branch.

2. Click the Run workflow button.

3. Select your branch.

4. Click Run workflow.

5. Once the workflow is done running, click into the related job.

6. In the Create and publish preview branch step, look for the preview branch's name.

7. Copy the preview branch's name.

8. In the Mintlify dashboard, click Create preview deployment.

9. Enter the preview branch's name.

10. Click Create deployment. A Manual update will display in the Previews table.

11. 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.