docs/.github/copilot-instructions.md

LangChain Documentation Guidelines

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

Critical rules

1. Always ask for clarification rather than making assumptions
2. Never use markdown in frontmatter description — breaks SEO
3. Never edit build/ — Mintlify build output (regenerate with make build or make dev)
4. Always update src/docs.json when adding new pages
5. Use Tabler icons only — not FontAwesome
6. Test code examples before including them

Repository structure

docs/
├── src/                        # All manually authored content
│   ├── docs.json               # Mintlify config + navigation (88KB)
│   ├── index.mdx               # Home page
│   ├── style.css               # Custom CSS
│   ├── langsmith/              # LangSmith product docs (~324 MDX files)
│   ├── oss/                    # Open source docs (~1800 MDX files)
│   │   ├── langchain/          #   LangChain framework
│   │   ├── langgraph/          #   LangGraph framework
│   │   ├── deepagents/         #   Deep Agents
│   │   ├── python/             #   Python-specific (integrations, migrations, releases)
│   │   ├── javascript/         #   TypeScript-specific (integrations, migrations, releases)
│   │   ├── integrations/       #   Shared integration content
│   │   ├── concepts/           #   Conceptual overviews
│   │   ├── contributing/       #   Contribution guides
│   │   └── reference/          #   Reference tab entry pages (link to reference.langchain.com)
│   ├── snippets/               # Reusable MDX snippets
│   ├── images/                 # Documentation images
│   │   ├── brand/              #   Logos, favicons
│   │   └── providers/          #   Provider icons (dark/ and light/ variants)
│   └── fonts/                  # Font files
├── pipeline/                   # Python build system & preprocessors
├── build/                      # Build output — do not edit
├── scripts/                    # Helper utilities
└── tests/                      # Pipeline tests

Navigation map

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.

Home

Single page (src/index.mdx). No tabs.

LangSmith (src/langsmith/)

7 tabs, all files in src/langsmith/:

Tab	Groups
Get started	Account administration (Workspace setup, Users & access control, Billing & usage), Tools, Additional resources
Observability	Tracing setup (Integrations, Manual instrumentation), Configuration & troubleshooting, Viewing & managing traces, Automations, Feedback & evaluation, Monitoring & alerting
Evaluation	Datasets, Set up evaluations (Run, Types, Frameworks, Techniques, Tutorials), Analyze experiment results, Annotation & human feedback
Prompt engineering	Create and update prompts, Tutorials
Agent deployment	Configure app, Deployment guides, App development, Studio, Auth & access control, Server customization
Platform setup	Overview, Hybrid, Self-hosted (by cloud provider, Setup guides, Enable features, Configuration, External services, Auth)
Reference	LangSmith Deployment APIs, Releases

Fleet (src/langsmith/fleet/)

Flat groups (no tabs): Get started, Tools and integrations, Advanced, Additional resources

Open source (src/oss/)

2 language dropdowns (Python, TypeScript), each with 7 identical tabs:

Tab	Directory
Deep Agents	src/oss/deepagents/
LangChain	src/oss/langchain/
LangGraph	src/oss/langgraph/
Integrations	src/oss/python/integrations/ or src/oss/javascript/integrations/
Learn	src/oss/ (various)
Reference	src/oss/reference/ — short entry pages linking to reference.langchain.com
Contribute	src/oss/contributing/

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/JS pages)
• Code highlighting: # [!code highlight], # [!code ++], # [!code --]
• API reference links: @[ClassName] for first mention of SDK classes/methods

Style

Follow Google Developer Documentation Style Guide.

• Be concise — second-person imperative present tense
• Sentence-case headings with active verb, not gerund ("Add a tool" not "Adding a tool")
• American English spelling
• No markdown in description fields
• No absolute URLs for internal links
• No /python/ or /javascript/ in links (resolved by build pipeline)
• No FontAwesome icon names
• No H5 or H6 headings