Contributing to documentation ↗

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 and click Create deployment
4. Select the preview and click Visit to view

To redeploy with latest changes, click Redeploy on the dashboard.

Run quality checks#

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

# 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 section in the README.

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.

Documentation types#

All documentation falls under one of four categories:

Task-oriented instructions for users who know what they want to accomplish.

Explanations that provide deeper understanding and insights.

Technical descriptions of APIs and implementation details.

Lessons that guide users through practical activities to build understanding.

Where applicable, all documentation must have both Python and JavaScript/TypeScript content. For more details, see the co-locate Python and JavaScript/TypeScript content section.

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 and LangGraph tabs.

Conceptual guides#

Conceptual guide cover core concepts abstractly, providing deep understanding.

Reference#

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

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

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

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.

Writing standards#

Reference documentation has different standards - see the reference docs contributing guide for details.

Mintlify components#

Use Mintlify components to enhance readability:

• <span class="callout-start" data-callout-type="note"></span> for helpful supplementary information

• <span class="callout-start" data-callout-type="warning"></span> for important cautions and breaking changes

• <span class="callout-start" data-callout-type="tip"></span> for best practices and advice

• <span class="callout-start" data-callout-type="info"></span> for neutral contextual information

• <span class="callout-start" data-callout-type="check"></span> for success confirmations

• <span class="steps-start"></span> for an overview of sequential procedures. Not for long lists of steps or tutorials.

• <span class="tab-group-start"></span> for platform-specific content.

• <AccordionGroup> and <Accordion> for nice-to-have information that can be collapsed by default (e.g., full code examples).

• <span class="card-group-start" data-cols="2"></span> and <Card> for highlighting content.

• `` for multiple language examples.

• Always specify language tags on code blocks (e.g., ```python, ```javascript).

  • Titles for code blocks (e.g. Success, Error Response)

Page structure#

Every documentation page must begin with YAML frontmatter:

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

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

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 or tag a maintainer in your PR.

Quality standards#

General guidelines#

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:

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.