> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-lginte-1765488813-6406a61.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Contributing to documentation

Accessible documentation is a vital part of LangChain. We welcome both documentation for new features and [integrations](/oss/python/contributing/publish-langchain#adding-documentation), as well as community improvements to existing docs.

<Note>
  These are contribution guidelines for our open source projects, but they also apply to the [LangSmith documentation](/langsmith/home).
</Note>

## Contribute

### Quick edits

For quick changes like fixing typos or changing a link, you can edit directly on GitHub without setting up a local development environment:

<Info>
  **Prerequisites:**

  * A [GitHub](https://github.com/) account
  * Basic familiarity of the [fork-and-pull workflow](https://graphite.dev/guides/understanding-git-fork-pull-request-workflow) for contributing
</Info>

1. At the bottom of the page you want to edit, click the link **Edit the source of this page on GitHub**.
2. GitHub will prompt you to fork the repository to your account. Make sure to fork into your <Tooltip tip="If you clone to an organization, maintainers are unable to make edits, which may delay acceptance.">personal account</Tooltip>.
3. Make the changes directly in GitHub's web editor.
4. Click **Commit changes...** and give your commit a descriptive title like `fix(docs): summary of change`. If applicable, add an [extended description](https://www.gitkraken.com/learn/git/best-practices/git-commit-message#git-commit-message-structure).
5. GitHub will redirect you to create a pull request. Give it a title (often the same as the commit) and follow the PR template checklist.

<Note>
  Docs PRs are typically reviewed within a few days. Keep an eye on your PR to address any feedback from maintainers.

  Do not bump the PR unless you have new information to provide – maintainers will address it as their availability permits.
</Note>

### Larger edits and additions

For larger changes, additions, or ongoing contributions, it's necessary to set up a local development environment on your machine. Our documentation build pipeline offers local preview, important for ensuring your changes appear as intended before submitting.

#### Set up local environment

Before you can work on this project, ensure you have the following installed:

**Required:**

* `python >= 3.13, < 4.0`
* [**`uv`**](https://docs.astral.sh/uv/) - Python package manager (used for dependency management)
* [**Node.js**](https://nodejs.org/en) and [**`npm`**](https://www.npmjs.com/) - For Mintlify CLI and reference documentation builds
* [**Make**](https://www.gnu.org/software/make/) - For running build commands
* [**Git**](https://git-scm.com/) - For version control

**Optional but recommended:**

* **[`markdownlint-cli`](https://github.com/igorshubovych/markdownlint-cli)** - For linting markdown files

  ```bash theme={null}
  npm install -g markdownlint-cli
  ```

* **[`pnpm`](https://pnpm.io/)** - Required only if you're working on reference documentation

  ```bash theme={null}
  npm install -g pnpm@10.14.0
  ```

* **[Mintlify MDX VSCode extension](https://www.mintlify.com/blog/mdx-vscode-extension)**

**Setup steps:**

1. Clone the [`langchain-ai/docs`](https://github.com/langchain-ai/docs) repo. Follow the steps outlined in [`IDE_SETUP.md`](https://github.com/langchain-ai/docs/blob/main/IDE_SETUP.md).

2. Install dependencies:

   ```bash theme={null}
   make install
   ```

   This command will:

   * Install Python dependencies using `uv sync --all-groups`
   * Install Mintlify CLI globally via npm

3. Verify your setup:

   ```bash theme={null}
   make build
   ```

   This should build the documentation without errors.

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

```bash theme={null}
docs --help
```

Common commands:

* `docs dev` - Start development mode with file watching and hot reload
* `docs build` - Build documentation

See [Available commands](#available-commands) for more details.

#### Edit documentation

<Note>
  **Only edit files in `src/`** – The `build/` directory is automatically generated.
</Note>

1. Ensure your [environment is set up](#set-up-local-environment) and that you have followed the steps in [`IDE_SETUP.md`](https://github.com/langchain-ai/docs/blob/main/IDE_SETUP.md) to configure your IDE/editor to automatically apply the correct settings.

2. Edit files in `src/`
   * Make changes to markdown files and the build system will automatically detect changes and rebuild affected files.
   * If OSS content varies between Python and JavaScript/TypeScript, add content for [both in the same file](#co-locate-python-and-javascripttypescript-oss-content). Otherwise, content will be identical for both languages.
   * Use [Mintlify syntax](https://mintlify.com/docs) for formatting.

3. Start development mode to preview changes locally:

   ```bash theme={null}
   docs dev
   ```

   This starts a development server with hot reload at `http://localhost:3000`.

4. Iterate

   * Continue editing and see changes reflected immediately.
   * The development server rebuilds only changed files for faster feedback.

5. Run the [quality checks](#run-quality-checks) to ensure your changes are valid.

6. Get approval from the relevant reviewers.

   LangChain team members can [generate a sharable preview build](#create-a-sharable-preview-build)

7. [Publish to production](#publish-to-prod) (team members only).

#### Create a sharable preview build

<Note>
  Only LangChain team members can create sharable preview builds.
</Note>

<Accordion title="Instructions">
  Previews are useful for sharing work-in-progress changes with others.

  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 with the latest changes, click **Redeploy** on the Mintlify dashboard.
</Accordion>

#### Run quality checks

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

```bash theme={null}
# Check broken links
make mint-broken-links

# Format code automatically
make format

# Check for linting issues
make lint

# Fix markdown issues
make lint_md_fix

# Run tests to ensure your changes don't break existing functionality
make test
```

For more details, see the [available commands](https://github.com/langchain-ai/docs?tab=readme-ov-file#available-commands) section in the `README`.

<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.
</Important>

#### Publish to prod

<Note>
  Only internal team members can publish to production.
</Note>

<Accordion title="Instructions">
  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**.
</Accordion>

## Documentation types

All documentation falls under one of four categories:

<CardGroup cols={2}>
  <Card title="How-to guides" icon="wrench" href="#how-to-guides">
    Task-oriented instructions for users who know what they want to accomplish.
  </Card>

  <Card title="Conceptual guides" icon="lightbulb" href="#conceptual-guides">
    Explanations that provide deeper understanding and insights.
  </Card>

  <Card title="Reference" icon="book" href="#reference">
    Technical descriptions of APIs and implementation details.
  </Card>

  <Card title="Tutorials" icon="graduation-cap" href="#tutorials">
    Lessons that guide users through practical activities to build understanding.
  </Card>
</CardGroup>

<Note>
  Where applicable, all documentation must have both Python and JavaScript/TypeScript content. For more details, see the [co-locate Python and JavaScript/TypeScript content](#co-locate-python-and-javascripttypescript-content) section.
</Note>

### How-to guides

How-to guides are task-oriented instructions for users who know what they want to accomplish. Examples of how-to guides are on the [LangChain](/oss/python/langchain/overview) and [LangGraph](/oss/python/langgraph/overview) tabs.

<AccordionGroup>
  <Accordion title="Characteristics">
    * **Task-focused**: Focus on a specific task or problem
    * **Step-by-step**: Break down the task into smaller steps
    * **Hands-on**: Provide concrete examples and code snippets
  </Accordion>

  <Accordion title="Tips">
    * Focus on the **how** rather than the **why**
    * Use concrete examples and code snippets
    * Break down the task into smaller steps
    * Link to related conceptual guides and references
  </Accordion>

  <Accordion title="Examples">
    * [Messages](/oss/python/langchain/messages)
    * [Tools](/oss/python/langchain/tools)
    * [Streaming](/oss/python/langgraph/streaming)
  </Accordion>
</AccordionGroup>

### Conceptual guides

Conceptual guide cover core concepts abstractly, providing deep understanding.

<AccordionGroup>
  <Accordion title="Characteristics">
    * **Understanding-focused**: Explain why things work as they do
    * **Broad perspective**: Higher and wider view than other types
    * **Design-oriented**: Explain decisions and trade-offs
    * **Context-rich**: Use analogies and comparisons
  </Accordion>

  <Accordion title="Tips">
    * Focus on the **"why"** rather than the "how"
    * Provides supplementary information not necessarily required for feature usage
    * Can use analogies and reference alternatives
    * Avoid blending in too much reference content
    * Link to related tutorials and how-to guides
  </Accordion>

  <Accordion title="Examples">
    * [Memory](/oss/python/concepts/memory)
    * [Context](/oss/python/concepts/context)
    * [Graph API](/oss/python/langgraph/graph-api)
    * [Functional API](/oss/python/langgraph/functional-api)
  </Accordion>
</AccordionGroup>

### Reference

Reference documentation contains detailed, low-level information describing exactly what functionality exists and how to use it.

<CardGroup cols={2}>
  <Card title="Python reference" href="https://reference.langchain.com/python/" icon="python" arrow />

  <Card title="JavaScript/TypeScript reference" href="https://reference.langchain.com/javascript/" icon="js" arrow />
</CardGroup>

A good reference should:

* Describe what exists (all parameters, options, return values)
* Be comprehensive and structured for easy lookup
* Serve as the authoritative source for technical details

<AccordionGroup>
  <Accordion title="Contributing to references">
    See the contributing guide for [Python reference docs](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md).
  </Accordion>

  <Accordion title="LangChain reference best practices">
    * **Be consistent**; follow existing patterns for provider-specific documentation
    * Include both basic usage (code snippets) and common edge cases/failure modes
    * Note when features require specific versions
  </Accordion>

  <Accordion title="When to create new reference documentation">
    * New integrations or providers need dedicated reference pages
    * Complex configuration options require detailed explanation
    * API changes introduce new parameters or behavior
    * Community frequently asks questions about specific functionality
  </Accordion>
</AccordionGroup>

### Tutorials

Tutorials are longer form step-by-step guides that builds upon itself and takes users through a specific practical activity to build understanding. Tutorials are typically found on the [Learn](/oss/python/learn) tab.

<Note>
  We generally do not merge new tutorials from outside contributors without an acute need. If you feel that a certain topic is missing from docs or is not sufficiently covered, please [open a new issue](https://github.com/langchain-ai/docs/issues).
</Note>

<AccordionGroup>
  <Accordion title="Characteristics">
    * **Practical**: Focus on practical activities to build understanding.
    * **Step-by-step**: Break down the activity into smaller steps.
    * **Hands-on**: Provide sequential, working code snippets.
    * **Supplementary**: Provide additional context and information not necessarily required for feature usage.
  </Accordion>

  <Accordion title="Tips">
    * Code snippets should be sequential and working if the user follows the steps in order.
    * Provide some context for the activity, but link to related conceptual guides and references for more detailed information.
  </Accordion>

  <Accordion title="Examples">
    * [Semantic search](/oss/python/langchain/knowledge-base)
    * [RAG agent](/oss/python/langchain/rag)
  </Accordion>
</AccordionGroup>

## Writing standards

<Note>
  Reference documentation has different standards - see the [reference docs contributing guide](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md) for details.
</Note>

### Mintlify components

Use [Mintlify components](https://mintlify.com/docs/text) to enhance readability:

<Tabs>
  <Tab title="Callouts">
    * `<Note>` for helpful supplementary information
    * `<Warning>` for important cautions and breaking changes
    * `<Tip>` for best practices and advice
    * `<Info>` for neutral contextual information
    * `<Check>` for success confirmations
  </Tab>

  <Tab title="Structure">
    * `<Steps>` for an overview of sequential procedures. **Not** for long lists of steps or tutorials.
    * `<Tabs>` for platform-specific content.
    * `<AccordionGroup>` and `<Accordion>` for nice-to-have information that can be collapsed by default (e.g., full code examples).
    * `<CardGroup>` and `<Card>` for highlighting content.
  </Tab>

  <Tab title="Code">
    * `<CodeGroup>` for multiple language examples.
    * Always specify language tags on code blocks (e.g., ` ```python`, ` ```javascript`).
    * Titles for code blocks (e.g. `Success`, `Error Response`)
  </Tab>
</Tabs>

### Page structure

Every documentation page must begin with YAML frontmatter:

```yaml theme={null}
---
title: "Clear, specific title"
sidebarTitle: "Short title for the sidebar (optional)"
---
```

### Co-locate Python and JavaScript/TypeScript content

All documentation must be written in both Python and JavaScript/TypeScript when possible. To do so, we use a custom in-line syntax to differentiate between sections that should appear in one or both languages:

```mdx theme={null}
:::python
Python-specific content. In real docs, the preceding backslash (before `python`) is omitted.
:::

:::js
JavaScript/TypeScript-specific content. In real docs, the preceding backslash (before `js`) is omitted.
:::

Content for both languages (not wrapped)
```

This will generate two outputs (one for each language) at `/oss/python/concepts/foo.mdx` and `/oss/javascript/concepts/foo.mdx`. Each outputted page will need to be added to the `/src/docs.json` file to be included in the navigation.

<Note>
  We don't want a lack of parity to block contributions. If a feature is only available in one language, it's okay to have documentation only in that language until the other language catches up. In such cases, please include a note indicating that the feature is not yet available in the other language.

  If you need help translating content between Python and JavaScript/TypeScript, please ask in the [community slack](https://www.langchain.com/join-community) or tag a maintainer in your PR.
</Note>

## Quality standards

### General guidelines

<AccordionGroup>
  <Accordion title="Avoid duplication">
    Multiple pages covering the same material are difficult to maintain and cause confusion. There should be only one canonical page for each concept or feature. Link to other guides instead of re-explaining.
  </Accordion>

  <Accordion title="Link frequently">
    Documentation sections don't exist in a vacuum. Link to other sections frequently to allow users to learn about unfamiliar topics. This includes linking to API references and conceptual sections.
  </Accordion>

  <Accordion title="Be concise">
    Take a less-is-more approach. If another section with a good explanation exists, link to it rather than re-explain, unless your content presents a new angle.
  </Accordion>
</AccordionGroup>

### Accessibility requirements

Ensure documentation is accessible to all users:

* Structure content for easy scanning with headers and lists
* Use specific, actionable link text instead of "click here"
* Include descriptive alt text for all images and diagrams

### Cross-referencing

Use consistent cross-references to connect docs with API reference documentation.

**From docs to API reference:**

Use the `@[]` syntax to link to API reference pages:

```mdx theme={null}
See @[`ChatAnthropic`] for all configuration options.

The @[`bind_tools`][ChatAnthropic.bind_tools] method accepts...
```

The build pipeline transforms these into proper markdown links based on the current language scope (Python or JavaScript). For example, `@[ChatAnthropic]` becomes a link to the Python or JS API reference page depending on which version of the docs is being built, **but only if an entry exists in the `link_map.py` file!** See below for details.

<Accordion title="How autolinks work">
  The `@[]` syntax is processed by [`handle_auto_links.py`](https://github.com/langchain-ai/docs/blob/main/pipeline/preprocessors/handle_auto_links.py). It looks up link keys in [`link_map.py`](https://github.com/langchain-ai/docs/blob/main/pipeline/preprocessors/link_map.py), which contains dictionary mappings for both Python and JavaScript scopes.

  **Supported formats:**

  | Syntax                   | Result                                                                                     |
  | ------------------------ | ------------------------------------------------------------------------------------------ |
  | `@[ChatAnthropic]`       | Link with "ChatAnthropic" as the displayed text                                            |
  | ``@[`ChatAnthropic`]``   | Link with `` `ChatAnthropic` `` (code formatted) as text                                   |
  | `@[text][ChatAnthropic]` | Link with "text" as text and `ChatAnthropic` as the key in the link map                    |
  | `\@[ChatAnthropic]`      | Escaped: renders as literal `@[ChatAnthropic]` (no link – what's being used on this page!) |

  **Adding new links:**

  If a link isn't found in the map, it will be left unchanged in the output. To add a new autolink:

  1. Open `pipeline/preprocessors/link_map.py`
  2. Add an entry to the appropriate scope (`python` or `js`) in `LINK_MAPS`
  3. The key is the link name used in `@[key]` or `@[text][key]`, the value is the path relative to the reference host
</Accordion>

**From API reference stubs to OSS docs:**

See the [`README`](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md) for more information on linking from API reference stubs to Python OSS docs. Specifically see the `mkdocstrings` cross-reference [linking syntax](https://github.com/langchain-ai/docs/blob/main/reference/python/README.md#mkdocsmkdocstrings-python-cross-reference-linking-syntax).

## Get help

Our goal is to have the simplest developer setup possible. Should you experience any difficulty getting setup, please ask in the [community slack](https://www.langchain.com/join-community) or open a [forum post](https://forum.langchain.com/). Internal team members can reach out in the [#documentation](https://langchain.slack.com/archives/C04GWPE38LV) Slack channel.

***

<Callout icon="pen-to-square" iconType="regular">
  [Edit the source of this page on GitHub.](https://github.com/langchain-ai/docs/edit/main/src/oss/contributing/documentation.mdx)
</Callout>

<Tip icon="terminal" iconType="regular">
  [Connect these docs programmatically](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
</Tip>