# langchain-docs

**Repository Path**: tanglf/langchain-docs

## Basic Information

- **Project Name**: langchain-docs
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-01
- **Last Updated**: 2025-11-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# LangChain Docs

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

* 🏠 [`docs.langchain.com`](https://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](https://mintlify.com).
* 🛠️ `reference.langchain.com` is home to the API reference docs for LangChain, LangGraph, LangSmith, and LangChain integration packages (e.g. [`langchain-anthropic`](https://pypi.org/project/langchain-anthropic/), [`langchain-openai`](https://pypi.org/project/langchain-openai/)). These are static sites built from the source code and deployed to [Vercel](https://vercel.com).
  * [`Python reference`](https://reference.langchain.com/python/)
  * [`JavaScript/TypeScript reference`](https://reference.langchain.com/javascript/)

> [!IMPORTANT]
>
> * The LangSmith API and [SDK](https://github.com/langchain-ai/langsmith-sdk) references are not yet fully consolidated to this repo. Visit their documentation:
>   * [`HTTP API Reference`](https://api.smith.langchain.com/redoc)
>   * [`JavaScript/TypeScript SDK reference`](https://docs.smith.langchain.com/reference/js)

---

## Overview

```text
# --- 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
    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](https://github.com/langchain-ai/docs/actions/workflows/publish.yml) (requires authorization), and [preview branches](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) 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

Before making any changes, we encourage you to read the LangChain [contributing guide](https://docs.langchain.com/oss/python/contributing/documentation) to understand our documentation types and their writing and quality standards.

> [!IMPORTANT]
> The following steps refer to the [`docs.langchain.com`](https://docs.langchain.com) Mintlify documentation site. For contributing to reference docs, see the `README.md` file in the `/reference/python` and `/reference/javascript` directories.

### Set up a local dev environment

1. Clone this repo. Follow the steps outlined in [IDE_SETUP.md](./IDE_SETUP.md).
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:

   ```bash
   cd docs
   uv venv
   source .venv/bin/activate
   ```

5. Install dependencies:

   ```bash
   uv sync --all-groups
   ```

   ```bash
   npm i -g mint
   ```

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

```bash
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](https://mintlify.com/docs) 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
* **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

### Documentation syntax

Our primary docs the [Mintlify](https://mintlify.com/docs) platform for docs generation. Key features include:

* **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](https://mintlify.com/docs) for detailed syntax and component usage.

### Testing

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

```bash
make test
```

### Code quality

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

```bash
# 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](./IDE_SETUP.md) to configure your IDE/editor to automatically apply the correct settings.

1. **Start development mode:**

   ```bash
   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](https://github.com/langchain-ai/docs/actions/workflows/create-preview-branch.yml) 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](https://dashboard.mintlify.com/langchain-5e9cc07a/langchain-5e9cc07a?section=previews), 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](https://github.com/langchain-ai/docs/actions/workflows/publish.yml):

1. Go to [Publish documentation](https://github.com/langchain-ai/docs/actions/workflows/publish.yml).
2. Click the **Run workflow** button.
3. Select the **main** branch to deploy.
4. Click **Run workflow**.

---

## Troubleshooting

### `docs dev` not working / running

Re-do the [steps to set up your dev environment](#set-up-a-local-dev-environment), ensuring you have activated the virtual environment and installed all dependencies.

### Mintlify `.venv` parsing error

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

```txt
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):

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

2. **Run Mintlify commands from the build directory**:

   ```bash
   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:

```json
{
  "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.

### General Mintlify errors

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:

```bash
mint update

# or

npm install -g mint
```