Add Docs Page

Add or move a docs page

A page is not finished when the MDX file exists. It also needs a navigation entry, and a move or deletion needs a redirect. CI enforces both.

Read AGENTS.md for the navigation map, the style guide, and the frontmatter rules. This skill covers the procedure around them and does not repeat them.

Step 1. Choose the source directory

Use the "Source directory summary" table in AGENTS.md to go from subject to directory. Two traps:

• Directory names do not match navigation names. src/langsmith/fleet/ appears as "No-code agents"; src/langsmith/managed-deep-agents*.mdx appears under Build, not under a LangSmith menu.
• Lifecycle menus mix products. Build draws from both src/oss/ and src/langsmith/; Test, Deploy, and Monitor all draw from src/langsmith/.

Never write to build/. It is Mintlify output, regenerated by make build.

Step 2. Write the page

Required frontmatter:

---
title: Clear, concise page title
description: SEO summary with no markdown, no links, and no backticks
---

For OSS pages that differ by language, use :::python and :::js fences in one file rather than writing two files. The build pipeline emits both versions.

Step 3. Add the navigation entry

Navigation lives in src/docs.json under navigation.products. There are two products: products[0] is AGENT DEVELOPMENT LIFECYCLE (Home, Build, Test, Deploy, Monitor) and products[1] is PRODUCTS AND SETUP (LangSmith setup, LLM Gateway, No-code agents, Engine, Deep Agents Code).

Each menu item is addressed by its item key, then nests one of two ways:

• menu[].tabs[].pages[] for most menu items.
• menu[].dropdowns[].tabs[].pages[] for Build, which has Python and TypeScript dropdowns.

A pages array holds page-path strings and {"group": ..., "pages": [...]} objects, nested to any depth.

Three rules:

1. A language-versioned OSS page needs two entries. Build page paths carry the language segment (oss/python/deepagents/overview and oss/javascript/deepagents/overview), so one new page means one entry in the Python dropdown and one in the TypeScript dropdown. Omitting the TypeScript entry is the most common miss.
2. Page paths omit the src/ prefix and the file extension. src/langsmith/sandboxes.mdx is "langsmith/sandboxes".
3. A new group leads with an index page: "pages": ["group/index", "group/page"].

Integration pages are the exception. Add them to the component's index.mdx instead, and touch docs.json only when creating a brand-new component group.

Step 4. Add redirects for a move, rename, or deletion

For a move or rename of a file that was already on main, run the repo's mover first. It rewrites cross-references across the corpus, which hand-editing misses:

uv run docs mv src/langsmith/old-name.mdx src/langsmith/new-name.mdx --dry-run

Drop --dry-run once the preview looks right. Then add the redirect to the redirects array in src/docs.json:

{ "source": "/langsmith/old-name", "destination": "/langsmith/new-name" }

Redirect paths are site paths and start with /. A language-versioned page needs a redirect per language, plus one for the unversioned path if the old URL had one.

scripts/check_removed_pages_redirects.py runs in CI and fails the PR when a page leaves the navigation and its source file is gone with no redirect. The same script fails when docs.json names a page whose file does not exist, so a typo in a page path is caught there rather than at build time.

Step 4b. Two traps that fail silently

Extract a snippet once a block appears on three pages

AGENTS.md covers how to add a snippet. The rule for when: the same block repeated on three or more pages becomes one file under src/snippets/. A status callout duplicated across a page family means the wording change that retires it is an edit to every page in the family, and one will be missed.

Verify a new snippet reaches the build. The pipeline rewrites snippet imports to language-specific paths, so /snippets/langsmith/x.mdx becomes /snippets/python/langsmith/x.mdx in the output, and a missing target renders as nothing at all rather than as an error:

ls build/snippets/python/langsmith/<name>.mdx build/snippets/javascript/langsmith/<name>.mdx