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

bash
1# See all changed files on this branch
2git diff canary...HEAD --stat
3
4# See changes in specific areas
5git 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:

yaml
1# docs/02-pages/... file with shared content
2---
3source: app/building-your-application/optimizing/images
4---

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

Step 5: Validate changes

bash
1pnpm lint          # Check formatting
2pnpm prettier-fix  # Auto-fix formatting issues

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:

mdx
1---
2title: Feature Name
3description: Brief description of what this feature does.
4---
5
6{/* The content of this doc is shared between the app and pages router. You can use the `<PagesOnly>Content</PagesOnly>` component to add content that is specific to the Pages Router. Any shared content should not be wrapped in a component. */}
7
8Brief introduction to the feature.
9
10## Reference
11
12### Props
13
14<div style={{ overflowX: 'auto', width: '100%' }}>
15
16| Prop                    | Example            | Type   | Status   |
17| ----------------------- | ------------------ | ------ | -------- |
18| [`propName`](#propname) | `propName="value"` | String | Required |
19
20</div>
21
22#### `propName`
23
24Description of the prop.
25
26\`\`\`tsx filename="app/example.tsx" switcher
27// TypeScript example
28\`\`\`
29
30\`\`\`jsx filename="app/example.js" switcher
31// JavaScript example
32\`\`\`

Guide Template:

mdx
1---
2title: How to do X in Next.js
3nav_title: X
4description: Learn how to implement X in your Next.js application.
5---
6
7Introduction explaining why this guide is useful.
8
9## Prerequisites
10
11What the reader needs to know before starting.
12
13## Step 1: First Step
14
15Explanation and code example.
16
17\`\`\`tsx filename="app/example.tsx" switcher
18// Code example
19\`\`\`
20
21## Step 2: Second Step
22
23Continue with more steps...
24
25## Next Steps
26
27Related topics to explore.

Step 4: Add related links

Update frontmatter with related documentation:

yaml
1related:
2  title: Next Steps
3  description: Learn more about related features.
4  links:
5    - app/api-reference/functions/related-function
6    - app/guides/related-guide

Documentation Conventions

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

Quick Reference

Frontmatter (required):

yaml
1---
2title: Page Title (2-3 words)
3description: One or two sentences describing the page.
4---

Code blocks:

\`\`\`tsx filename="app/page.tsx" switcher
// TypeScript first
\`\`\`

\`\`\`jsx filename="app/page.js" switcher
// JavaScript second
\`\`\`

Router-specific content:

mdx
1<AppOnly>Content only for App Router docs.</AppOnly>
2
3<PagesOnly>Content only for Pages Router docs.</PagesOnly>

Notes:

mdx
1> **Good to know**: Single line note.
2
3> **Good to know**:
4>
5> - Multi-line note point 1
6> - Multi-line note point 2

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