mirror of
https://github.com/langchain-ai/docs.git
synced 2026-08-27 21:00:00 -04:00
Lauren Hirata Singh
392db4cdf8
## 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>
69 lines
3.1 KiB
Plaintext
69 lines
3.1 KiB
Plaintext
# 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 `.cursor/rules/docs-style.mdc` and load automatically when you edit `src/**/*.mdx`.
|
|
|
|
## Critical rules
|
|
|
|
1. **Always ask for clarification** rather than making assumptions
|
|
2. **Never fabricate** examples, JSON snippets, policy details, or use case descriptions — use only content from the user or existing source files
|
|
3. **Never use markdown in frontmatter `description`** — breaks SEO
|
|
4. **Never edit `build/`** — Mintlify build output (regenerate with `make build` or `make dev`)
|
|
5. **Always update `src/docs.json`** when adding new pages
|
|
6. **Use Tabler icons only** — not FontAwesome
|
|
7. **Test code examples** before including them
|
|
8. **Always run `make lint_prose`** on changed files before committing — CI blocks on it
|
|
|
|
## Repository structure
|
|
|
|
```txt
|
|
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:
|
|
|
|
```yaml
|
|
---
|
|
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
|