Skip to content

Update Docs Contributing guide #1363

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Nov 10, 2025
Merged

Update Docs Contributing guide #1363

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
de83666
contributing
lnhsingh Nov 10, 2025
16f4ead
fix broken links
lnhsingh Nov 10, 2025
0d41932
Merge branch 'main' into contrib
lnhsingh Nov 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
217 changes: 19 additions & 198 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,23 +13,17 @@
> * [`HTTP API Reference`](https://api.smith.langchain.com/redoc)
> * [`JavaScript/TypeScript SDK reference`](https://docs.smith.langchain.com/reference/js)

---

**Table of contents:**

- [LangChain Docs](#langchain-docs)
- [Repository structure](#repository-structure)
- [`docs.langchain.com`](#docslangchaincom)
- [`reference.langchain.com`](#referencelangchaincom)
- [Contributing](#contributing)
- [Set up a local dev environment](#set-up-a-local-dev-environment)
- [Workflow](#workflow)
- [Co-locate Python and JavaScript/TypeScript OSS content](#co-locate-python-and-javascripttypescript-oss-content)
- [Localized content](#localized-content)
- [Create a preview build](#create-a-preview-build)
- [Quality checks](#quality-checks)
- [Publish to prod](#publish-to-prod)
- [Contribute](#contribute)
- [Reference](#reference)
- [Repository structure](#repository-structure)
- [`docs.langchain.com`](#docslangchaincom)
- [`reference.langchain.com`](#referencelangchaincom)
- [File formats](#file-formats)
- [Documentation syntax](#documentation-syntax)
- [Available commands](#available-commands)
- [Troubleshooting](#troubleshooting)
- [`docs dev` not working / running](#docs-dev-not-working--running)
Expand All @@ -39,7 +33,16 @@

---

## Repository structure
## Contribute

To contribute to LangChain documentation, follow the steps outlined in the [contributing guide](/oss/contributing/documentation). The contributing guide also explains our documentation types and their writing and quality standards.

> [!IMPORTANT]
> For contributing to reference docs, see the `README.md` file in the `/reference/python` and `/reference/javascript` directories.

## Reference

### Repository structure

```text
# --- docs.langchain.com ----------------------------------------------
Expand All @@ -63,7 +66,7 @@ reference/ # Reference docs build pipelines
vercel.json # Vercel configuration/redirects
```

### `docs.langchain.com`
#### `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.

Expand All @@ -72,200 +75,21 @@ The Mintlify docs pipeline is structured with `.mdx` source files in `/src` and

The `/src/docs.json` file is used to configure the Mintlify site navigation and settings. Refer to the [Mintlify documentation](https://www.mintlify.com/docs/organize/navigation) for detailed syntax and component usage.

Documentation changes follow a PR [workflow](#workflow) where all tests must pass before merging.
Documentation changes follow a PR workflow where all tests must pass before merging. See the [contributing guidelines](/oss/contributing/documentation) for more details.

### `reference.langchain.com`
#### `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

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

### Workflow

> [!IMPORTANT]
> * **Only edit files in `src/`** - The `build/` directory is automatically generated
> * **Use Mintlify syntax** - See [Mintlify documentation](https://mintlify.com/docs) for formatting guidelines

1. Ensure your [dev environment is set up](#set-up-local-dev-environment) 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.

2. Start development mode:

```bash
docs dev
```

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

3. Edit files in `src/`:
* Make changes to markdown files, notebooks, or other documentation
* The build system automatically detects changes and rebuilds 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.
* If [adding localized content](#localized-content), add content in the specific language directory (e.g.,`src/ko/` for Korean).

4. Use `docs dev` to [preview changes](#create-a-preview-build) locally with hot reload. Changes automatically appear in your browser at <http://localhost:3000>.

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

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

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

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

In the `/oss` directory, we have a custom syntax for co-locating Python and JavaScript/TypeScript content in the same file. Use the `:::python` and `:::js` code language fences to tag the content that is specific to that language and will generate two outputs (one for each language). These are closed with the `:::` fence.

For example, if you have a file in `/oss/concepts/foo.mdx`, you can use the following syntax to co-locate Python and JavaScript/TypeScript content:

```mdx
:::python
This is Python-specific content.
:::

:::js
This is JavaScript/TypeScript-specific content.
:::
```

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.

### Localized content

> [!IMPORTANT]
> Currently, the LangChain documentation is only available in English, but we are working to add support for other languages, thanks to our LangChain Ambassadors!

To add localized content (content in a specific language), place it in the corresponding language directory. Each language has its own directory named after its language code. For more information, refer to the [Mintlify documentation](https://www.mintlify.com/docs/organize/navigation#languages) for more details on localized content.

```text
src/
langsmith/ # English - LangSmith docs
oss/ # English - LangChain, LangGraph, Deep Agents, and integrations docs
...
cn/ # Chinese (Simplified) - No content yet
es/ # Spanish - No content yet
ko/ # Korean - No content yet
zh-Hant/ # Chinese (Traditional) - No content yet
```

### 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. Previews are useful for sharing work-in-progress changes with others.

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.


### Quality checks

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

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

> [!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.

### Publish to prod

> [!IMPORTANT]
> Only internal team members can publish to production.

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

## Reference

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

### Available commands

**Make commands:**
Expand Down Expand Up @@ -314,9 +138,6 @@ These can be used directly using the `Makefile` or via the `docs` CLI tool:
* **`docs build`** - Build documentation files
* `--watch` - Watch for file changes after building


---

## Troubleshooting

### `docs dev` not working / running
Expand Down
46 changes: 46 additions & 0 deletions reference/python/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -546,3 +546,49 @@ title: Chat models (Classic)
```

---

## In-code documentation

### Language and style

> [!NOTE]
> Use [Google-style docstrings](https://google.github.io/styleguide/pyguide.html) with complete type hints for all public functions.

Follow these standards for all documentation:

- **Voice**: Use second person ("you") for instructions
- **Tense**: Use active voice and present tense
- **Clarity**: Write clear, direct language for technical audiences
- **Consistency**: Use consistent terminology throughout
- **Conciseness**: Keep sentences concise while providing necessary context

### Code examples

> [!WARNING]
> Always test code examples before publishing. Never include real API keys or secrets.

Requirements for code examples:

- **Completeness**: Include complete, runnable examples that users can copy and execute without errors
- **Realism**: Use realistic data instead of placeholder values like "foo" or "example"
- **Error handling**: Show proper error handling and edge case management
- **Documentation**: Add explanatory comments for complex logic

Example of a well-documented function:

```python
def filter_unknown_users(users: list[str], known_users: set[str]) -> list[str]:
"""Filter out users that are not in the known users set.

Args:
users: List of user identifiers to filter.
known_users: Set of known/valid user identifiers.

Returns:
List of users that are not in the known_users set.

Raises:
ValueError: If users list contains invalid identifiers.
"""
return [user for user in users if user not in known_users]
```
Loading