|
1 | | -# LangChain's unified documentation overview |
| 1 | +# LangChain Documentation Guidelines |
2 | 2 |
|
3 | | -This repository encompasses the comprehensive documentation for LangChain's products and services, hosted on the Mintlify platform. The documentation is divided into sections for each product. This is a shared set of guidelines to ensure consistency and quality across all content. |
| 3 | +Documentation for LangChain products hosted on Mintlify. These guidelines apply to manually authored docs only—not `**/reference/**` directories or build artifacts. |
4 | 4 |
|
5 | | -## Scope |
| 5 | +## Critical rules |
6 | 6 |
|
7 | | -**These instructions apply to manually authored documentation only. They do NOT apply to:** |
| 7 | +1. **Always ask for clarification** rather than making assumptions |
| 8 | +2. **Never use markdown in frontmatter `description`** — breaks SEO |
| 9 | +3. **Never edit `reference/` directory** — auto-generated |
| 10 | +4. **Always update `src/docs.json`** when adding new pages |
| 11 | +5. **Use Tabler icons only** — not FontAwesome |
| 12 | +6. **Test code examples** before including them |
8 | 13 |
|
9 | | -- Files in `**/reference/**` directories (auto-generated API reference documentation) |
10 | | -- Build artifacts and generated files |
| 14 | +## Repository structure |
11 | 15 |
|
12 | | -For reference documentation, see `.github/instructions/reference-docs.instructions.md`. |
13 | | - |
14 | | -## Working relationship |
15 | | - |
16 | | -- You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so |
17 | | -- ALWAYS ask for clarification rather than making assumptions |
18 | | -- NEVER lie, guess, or make up information |
19 | | - |
20 | | -## Project context |
21 | | - |
22 | | -- Format: MDX files with YAML frontmatter. Mintlify syntax. |
23 | | -- Config: docs.json for navigation, theme, settings |
24 | | -- Components: Mintlify components |
25 | | - |
26 | | -## Content strategy |
27 | | - |
28 | | -- Document just enough for user success - not too much, not too little |
29 | | -- Prioritize accuracy and usability of information |
30 | | -- Make content evergreen when possible |
31 | | -- Search for existing information before adding new content. Avoid duplication unless it is done for a strategic reason. Reference existing content when possible |
32 | | -- Check existing patterns for consistency |
33 | | -- Start by making the smallest reasonable changes |
34 | | - |
35 | | -## docs.json |
36 | | - |
37 | | -- Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation |
38 | | -- If adding a new group, ensure the root `index.mdx` is included in the `pages` array like: |
39 | | - |
40 | | -```json |
41 | | -{ |
42 | | - "group": "New group", |
43 | | - "pages": ["new-group/index", "new-group/other-page"] |
44 | | -} |
| 16 | +``` |
| 17 | +docs/ |
| 18 | +├── src/ # All manually authored content |
| 19 | +│ ├── docs.json # Mintlify config + navigation (88KB) |
| 20 | +│ ├── index.mdx # Home page |
| 21 | +│ ├── style.css # Custom CSS |
| 22 | +│ ├── langsmith/ # LangSmith product docs (~324 MDX files) |
| 23 | +│ ├── oss/ # Open source docs (~1800 MDX files) |
| 24 | +│ │ ├── langchain/ # LangChain framework |
| 25 | +│ │ ├── langgraph/ # LangGraph framework |
| 26 | +│ │ ├── deepagents/ # Deep Agents |
| 27 | +│ │ ├── python/ # Python-specific (integrations, migrations, releases) |
| 28 | +│ │ ├── javascript/ # TypeScript-specific (integrations, migrations, releases) |
| 29 | +│ │ ├── integrations/ # Shared integration content |
| 30 | +│ │ ├── concepts/ # Conceptual overviews |
| 31 | +│ │ └── contributing/ # Contribution guides |
| 32 | +│ ├── snippets/ # Reusable MDX snippets |
| 33 | +│ ├── images/ # Documentation images |
| 34 | +│ │ ├── brand/ # Logos, favicons |
| 35 | +│ │ └── providers/ # Provider icons (dark/ and light/ variants) |
| 36 | +│ └── fonts/ # Font files |
| 37 | +├── pipeline/ # Python build system & preprocessors |
| 38 | +├── reference/ # Auto-generated API reference — do not edit |
| 39 | +├── build/ # Build output — do not edit |
| 40 | +├── scripts/ # Helper utilities |
| 41 | +└── tests/ # Pipeline tests |
45 | 42 | ``` |
46 | 43 |
|
47 | | -If the trailing `/index` (no extension included) is omitted, the Mintlify parser will raise a warning even though the site will still build. |
48 | | - |
49 | | -## Frontmatter requirements for pages |
50 | | - |
51 | | -- title: Clear, descriptive, concise page title |
52 | | -- description: Concise summary for SEO/navigation |
53 | | - |
54 | | -## Custom code language fences |
55 | | - |
56 | | -We have implemented custom code language fences for Python and JavaScript/TypeScript. They are used to tag content that is specific to that language. Use either `:::python` or `:::js` to tag content that is specific to that language. Both are closed with the `:::` fence. |
57 | | - |
58 | | -If any code fences like this exist on the code page, then two outputs (one for each language) will be created. For example, if this syntax is on the page in `/concepts/foo.mdx`, two pages will be created at `/python/concepts/foo.mdx` and `/javascript/concepts/foo.mdx`. |
59 | | - |
60 | | -For implementation details, see `pipeline/preprocessors/markdown_preprocessor.py`. |
61 | | - |
62 | | -## Snippets |
63 | | - |
64 | | -Snippet files in `src/snippets/` are reusable MDX content that can be imported into multiple pages. These snippets undergo special link preprocessing during the build process that converts absolute `/oss/` links to relative paths. |
65 | | - |
66 | | -**Important:** When writing links in snippets, be careful about path segments. Read the docstrings and comments in `pipeline/core/builder.py` method `_process_snippet_markdown_file` (lines 807-872) to understand how snippet link preprocessing works and why certain path structures are required. |
67 | | - |
68 | | -## Style guide |
| 44 | +## Navigation map |
| 45 | + |
| 46 | +Navigation is defined in `src/docs.json`. The site has 4 products. When adding pages, find the correct product/tab/group below, then update the matching section in `docs.json`. |
| 47 | + |
| 48 | +### Home |
| 49 | +Single page (`src/index.mdx`). No tabs. |
| 50 | + |
| 51 | +### LangSmith (`src/langsmith/`) |
| 52 | +7 tabs, all files in `src/langsmith/`: |
| 53 | + |
| 54 | +| Tab | Groups | |
| 55 | +|-----|--------| |
| 56 | +| Get started | Account administration (Workspace setup, Users & access control, Billing & usage), Tools, Additional resources | |
| 57 | +| Observability | Tracing setup (Integrations, Manual instrumentation), Configuration & troubleshooting, Viewing & managing traces, Automations, Feedback & evaluation, Monitoring & alerting | |
| 58 | +| Evaluation | Datasets, Set up evaluations (Run, Types, Frameworks, Techniques, Tutorials), Analyze experiment results, Annotation & human feedback | |
| 59 | +| Prompt engineering | Create and update prompts, Tutorials | |
| 60 | +| Agent deployment | Configure app, Deployment guides, App development, Studio, Auth & access control, Server customization | |
| 61 | +| Platform setup | Overview, Hybrid, Self-hosted (by cloud provider, Setup guides, Enable features, Configuration, External services, Auth) | |
| 62 | +| Reference | LangSmith Deployment APIs, Releases | |
| 63 | + |
| 64 | +### Agent Builder (`src/langsmith/agent-builder/`) |
| 65 | +Flat groups (no tabs): Get started, Tools and integrations, Advanced, Additional resources |
| 66 | + |
| 67 | +### Open source (`src/oss/`) |
| 68 | +2 language dropdowns (Python, TypeScript), each with 7 identical tabs: |
| 69 | + |
| 70 | +| Tab | Directory | |
| 71 | +|-----|-----------| |
| 72 | +| Deep Agents | `src/oss/deepagents/` | |
| 73 | +| LangChain | `src/oss/langchain/` | |
| 74 | +| LangGraph | `src/oss/langgraph/` | |
| 75 | +| Integrations | `src/oss/python/integrations/` or `src/oss/javascript/integrations/` | |
| 76 | +| Learn | `src/oss/` (various) | |
| 77 | +| Reference | `reference/` — auto-generated, do not edit | |
| 78 | +| Contribute | `src/oss/contributing/` | |
| 79 | + |
| 80 | +## Quick reference |
| 81 | + |
| 82 | +| What | Where/How | |
| 83 | +|------|-----------| |
| 84 | +| Navigation config | `src/docs.json` | |
| 85 | +| Reusable snippets | `src/snippets/` | |
| 86 | +| Provider icons | `src/images/providers/` | |
| 87 | +| Icon library | Tabler — https://tabler.io/icons | |
| 88 | +| Mintlify components | https://mintlify.com/docs/components | |
| 89 | +| Auto-link syntax | `@[ClassName]` — defined in `pipeline/preprocessors/link_map.py` | |
| 90 | + |
| 91 | +## Frontmatter |
| 92 | + |
| 93 | +Every MDX file requires: |
| 94 | + |
| 95 | +```yaml |
| 96 | +--- |
| 97 | +title: Clear, concise page title |
| 98 | +description: SEO summary — no markdown allowed (no links, backticks, formatting) |
| 99 | +--- |
| 100 | +``` |
69 | 101 |
|
70 | | -In general, follow the [Google Developer Documentation Style Guide](https://developers.google.com/style). You can also access this style guide through the [Vale-compatible implementation](https://github.com/errata-ai/Google). |
| 102 | +## Syntax |
71 | 103 |
|
72 | | -- Second-person voice ("you") |
73 | | -- Prerequisites at start of procedural content |
74 | | -- Test all code examples before publishing |
75 | | -- Match style and formatting of existing pages |
76 | | -- Include both basic and advanced use cases |
77 | | -- Language tags on all code blocks |
78 | | -- Alt text on all images |
79 | | -- Root relative paths for internal links |
80 | | -- Correct spelling |
81 | | -- Correct grammar |
82 | | -- Sentence-case for headings |
83 | | -- Ensure American English spelling |
| 104 | +- Language-specific content: `:::python` or `:::js` fences (generates separate Python/JS pages) |
| 105 | +- Code highlighting: `# [!code highlight]`, `# [!code ++]`, `# [!code --]` |
| 106 | +- API reference links: `@[ClassName]` for first mention of SDK classes/methods |
84 | 107 |
|
85 | | -## Do not |
| 108 | +## Style |
86 | 109 |
|
87 | | -- Do not skip frontmatter on any MDX file |
88 | | -- Do not use absolute URLs for internal links |
89 | | -- Do not review code blocks (denoted by ```), as they are often not full snippets |
90 | | -- Do not include untested code examples |
91 | | -- Do not make assumptions - always ask for clarification |
92 | | -- Do not include localization in relative links (e.g., `/python/` or `/javascript/`) - these are resolved automatically by the build pipeline |
| 110 | +Follow [Google Developer Documentation Style Guide](https://developers.google.com/style). |
93 | 111 |
|
94 | | -For questions, refer to the Mintlify docs (either via MCP, if available), or at the [Mintlify documentation](https://docs.mintlify.com/docs/introduction). |
| 112 | +- Be concise — second-person imperative present tense |
| 113 | +- Sentence-case headings with active verb, not gerund ("Add a tool" not "Adding a tool") |
| 114 | +- American English spelling |
| 115 | +- No markdown in description fields |
| 116 | +- No absolute URLs for internal links |
| 117 | +- No `/python/` or `/javascript/` in links (resolved by build pipeline) |
| 118 | +- No FontAwesome icon names |
| 119 | +- No H5 or H6 headings |
0 commit comments