mirror of https://github.com/langchain-ai/docs.git synced 2026-08-27 10:52:15 -04:00

Files

T

Lauren Hirata Singh 392db4cdf8 docs: give Cursor and Copilot the full prose style guide (#5473 )

## Why

`.cursorrules` and `.github/copilot-instructions.md` were
hand-maintained subsets of `CLAUDE.md`. Comparing headings, the subsets
dropped 26 of them, including the whole style guide and the structure
conventions:

```console
$ diff <(grep -E "^#{2,3} " CLAUDE.md) <(grep -E "^#{2,3} " .cursorrules) | grep '^<'
< ## Style guide
< ### Structure conventions
< ### Model references
< ### Release stage names
< ### Product and feature name capitalization
< ## Components
< ## Mermaid diagram styling
...
```

So a contributor on Cursor or Copilot got the repository layout and none
of the rules about how the prose should read.

They are also stale. Both last changed **2026-05-13**; `CLAUDE.md` last
changed **2026-07-22**. The product and feature name capitalization rule
added in #5036 never reached either file.

## What changed

Rather than copying all 398 lines into every file, the style guide is
mirrored into two path-scoped rule files, which is each tool's native
way to attach rules to file patterns:

| File | Scoping | Loads when |
|------|---------|-----------|
| `.cursor/rules/docs-style.mdc` | `globs: src/**/*.mdx` | Editing a
page under `src/` |
| `.github/instructions/docs-style.instructions.md` | `applyTo:
"src/**/*.mdx"` | Editing a page under `src/` |

Both bodies are byte-identical to lines 219 to 309 of `CLAUDE.md`,
verified with `diff`. The scoping matches 2,275 MDX files under `src/`.

`.cursorrules` and `copilot-instructions.md` are trimmed to what applies
to every task: critical rules, repository structure, quick reference,
frontmatter, syntax, and a pointer to `AGENTS.md`. Both are 68 lines and
differ only in the line naming their own style rule file.

The sync banner at the top of `CLAUDE.md` and `AGENTS.md` now names all
four derived files and says which sections feed each, so the next style
guide edit updates them in the same PR.

## Removed on purpose

The trimmed files no longer carry a navigation map. The one they had was
wrong: it listed the LangSmith "Configure app" tab and Fleet's "Tools
and integrations" group, neither of which exists now. `AGENTS.md` has
the current map, and the trimmed files point at it. Restating it in four
places is what produced the staleness in the first place.

## Review notes

Two things worth a second opinion:

1. **The cut line.** Only the style guide is path-scoped. Frontmatter,
components, and Mermaid styling rules still live only in `CLAUDE.md` and
`AGENTS.md`, though they are just as relevant when editing an MDX file.
Extending the scoped files to cover them is a reasonable follow-up; it
was left out to keep this reviewable.
2. **Sync is still manual.** The banner tells a human what to update. It
does not enforce anything. A CI drift check would, and is the obvious
next step if this pattern holds.

No page content is touched, so there is nothing to preview.

Drafted with Claude Code.

Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-08-12 13:38:39 -07:00

3.1 KiB

Raw Permalink Blame History

LangChain Documentation Guidelines

Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored content under src/, not Mintlify build/ output.

AGENTS.md in the repository root is the authoritative guide. Read it before making any non-trivial change. This file carries only the rules that apply to every task.

Prose style rules (voice, headings, terminology, page structure) live in .github/instructions/docs-style.instructions.md and load automatically when you edit src/**/*.mdx.

Critical rules

Always ask for clarification rather than making assumptions
Never fabricate examples, JSON snippets, policy details, or use case descriptions — use only content from the user or existing source files
Never use markdown in frontmatter description — breaks SEO
Never edit build/ — Mintlify build output (regenerate with make build or make dev)
Always update src/docs.json when adding new pages
Use Tabler icons only — not FontAwesome
Test code examples before including them
Always run make lint_prose on changed files before committing — CI blocks on it

Repository structure

docs/
├── src/                        # All manually authored content
│   ├── docs.json               # Mintlify config + navigation
│   ├── index.mdx               # Home page
│   ├── style.css               # Custom CSS
│   ├── langsmith/              # LangSmith product docs
│   │   └── fleet/              #   LangSmith Fleet
│   ├── oss/                    # Open source docs (LangChain, LangGraph, Deep Agents)
│   ├── snippets/               # Reusable MDX snippets
│   ├── images/                 # Documentation images
│   └── fonts/                  # Font files
├── pipeline/                   # Python build system & preprocessors
├── build/                      # Build output — do not edit
├── scripts/                    # Helper utilities
└── tests/                      # Pipeline tests

For the navigation map (every product, tab, and group), see AGENTS.md. Navigation is defined in src/docs.json, and new pages must be added to the correct product, tab, and group.

Quick reference

What	Where/How
Navigation config	`src/docs.json`
Reusable snippets	`src/snippets/`
Provider icons	`src/images/providers/`
Icon library	Tabler, https://tabler.io/icons
Mintlify components	https://mintlify.com/docs/components
Auto-link syntax	`@[ClassName]`, defined in `pipeline/preprocessors/link_map.py`

Frontmatter

Every MDX file requires:

---
title: Clear, concise page title
description: SEO summary — no markdown allowed (no links, backticks, formatting)
---

Syntax

Language-specific content: :::python or :::js fences (generates separate Python and TypeScript pages)
Code highlighting: # [!code highlight], # [!code ++], # [!code --]
API reference links: @[ClassName] for the first mention of SDK classes or methods

3.1 KiB Raw Permalink Blame History