update-docs

Next.js Documentation Updater

Guides you through updating Next.js documentation based on code changes on the active branch. Designed for maintainers reviewing PRs for documentation completeness.

Quick Start

1. Analyze changes: Run git diff canary...HEAD --stat to see what files changed
2. Identify affected docs: Map changed source files to documentation paths
3. Review each doc: Walk through updates with user confirmation
4. Validate: Run pnpm lint to check formatting
5. Commit: Stage documentation changes

Workflow: Analyze Code Changes

Step 1: Get the diff

# See all changed files on this branch
git diff canary...HEAD --stat
 
# See changes in specific areas
git diff canary...HEAD -- packages/next/src/

Step 2: Identify documentation-relevant changes

Look for changes in these areas:

Step 3: Map to documentation files

Use the code-to-docs mapping in references/CODE-TO-DOCS-MAPPING.md to find corresponding documentation files.

Example mappings:

• src/client/components/image.tsx → docs/01-app/03-api-reference/02-components/image.mdx
• src/server/config-shared.ts → docs/01-app/03-api-reference/05-config/

Workflow: Update Existing Documentation

Step 1: Read the current documentation

Before making changes, read the existing doc to understand:

• Current structure and sections
• Frontmatter fields in use
• Whether it uses <AppOnly> / <PagesOnly> for router-specific content

Step 2: Identify what needs updating

Common updates include:

• New props/options: Add to the props table and create a section explaining usage
• Changed behavior: Update descriptions and examples
• Deprecated features: Add deprecation notices and migration guidance
• New examples: Add code blocks following conventions

Step 3: Apply updates with confirmation

For each change:

1. Show the user what you plan to change
2. Wait for confirmation before editing
3. Apply the edit
4. Move to the next change

Step 4: Check for shared content

If the doc uses the source field pattern (common for Pages Router docs), the source file is the one to edit. Example:

# docs/02-pages/... file with shared content
---
source: app/building-your-application/optimizing/images
---

Edit the App Router source, not the Pages Router file.

Step 5: Validate changes

Workflow: Scaffold New Feature Documentation

Use this when adding documentation for entirely new features.

Step 1: Determine the doc type

Step 2: Create the file with proper naming

• Use kebab-case: my-new-feature.mdx
• Add numeric prefix if ordering matters: 05-my-new-feature.mdx
• Place in the correct directory based on feature type

Step 3: Use the appropriate template

API Reference Template:

Guide Template:

Step 4: Add related links

Update frontmatter with related documentation:

Documentation Conventions

See references/DOC-CONVENTIONS.md for complete formatting rules.

Quick Reference

Frontmatter (required):

Code blocks:

Router-specific content:

Notes:

Validation Checklist

Before committing documentation changes:

• Frontmatter has title and description
• Code blocks have filename attribute
• TypeScript examples use switcher with JS variant
• Props tables are properly formatted
• Related links point to valid paths
• pnpm lint passes
• Changes render correctly (if preview available)

References

• references/DOC-CONVENTIONS.md - Complete frontmatter and formatting rules
• references/CODE-TO-DOCS-MAPPING.md - Source code to documentation mapping