update-docs

1---2name: update-docs3description: This skill should be used when the user asks to "update documentation for my changes", "check docs for this PR", "what docs need updating", "sync docs with code", "scaffold docs for this feature", "document this feature", "review docs completeness", "add docs for this change", "what documentation is affected", "docs impact", or mentions "docs/", "docs/01-app", "docs/02-pages", "MDX", "documentation update", "API reference", ".mdx files". Provides guided workflow for updating Next.js documentation based on code changes.4metadata:5  internal: true6---7 8# Next.js Documentation Updater9 10Guides you through updating Next.js documentation based on code changes on the active branch. Designed for maintainers reviewing PRs for documentation completeness.11 12## Quick Start13 141. **Analyze changes**: Run `git diff canary...HEAD --stat` to see what files changed152. **Identify affected docs**: Map changed source files to documentation paths163. **Review each doc**: Walk through updates with user confirmation174. **Validate**: Run `pnpm lint` to check formatting185. **Commit**: Stage documentation changes19 20## Workflow: Analyze Code Changes21 22### Step 1: Get the diff23 24```bash25# See all changed files on this branch26git diff canary...HEAD --stat27 28# See changes in specific areas29git diff canary...HEAD -- packages/next/src/30```31 32### Step 2: Identify documentation-relevant changes33 34Look for changes in these areas:35 36| Source Path                            | Likely Doc Impact           |37| -------------------------------------- | --------------------------- |38| `packages/next/src/client/components/` | Component API reference     |39| `packages/next/src/server/`            | Function API reference      |40| `packages/next/src/shared/lib/`        | Varies by export            |41| `packages/next/src/build/`             | Configuration or build docs |42| `packages/next/src/lib/`               | Various features            |43 44### Step 3: Map to documentation files45 46Use the code-to-docs mapping in `references/CODE-TO-DOCS-MAPPING.md` to find corresponding documentation files.47 48Example mappings:49 50- `src/client/components/image.tsx` → `docs/01-app/03-api-reference/02-components/image.mdx`51- `src/server/config-shared.ts` → `docs/01-app/03-api-reference/05-config/`52 53## Workflow: Update Existing Documentation54 55### Step 1: Read the current documentation56 57Before making changes, read the existing doc to understand:58 59- Current structure and sections60- Frontmatter fields in use61- Whether it uses `<AppOnly>` / `<PagesOnly>` for router-specific content62 63### Step 2: Identify what needs updating64 65Common updates include:66 67- **New props/options**: Add to the props table and create a section explaining usage68- **Changed behavior**: Update descriptions and examples69- **Deprecated features**: Add deprecation notices and migration guidance70- **New examples**: Add code blocks following conventions71 72### Step 3: Apply updates with confirmation73 74For each change:75 761. Show the user what you plan to change772. Wait for confirmation before editing783. Apply the edit794. Move to the next change80 81### Step 4: Check for shared content82 83If the doc uses the `source` field pattern (common for Pages Router docs), the source file is the one to edit. Example:84 85```yaml86# docs/02-pages/... file with shared content87---88source: app/building-your-application/optimizing/images89---90```91 92Edit the App Router source, not the Pages Router file.93 94### Step 5: Validate changes95 96```bash97pnpm lint          # Check formatting98pnpm prettier-fix  # Auto-fix formatting issues99```100 101## Workflow: Scaffold New Feature Documentation102 103Use this when adding documentation for entirely new features.104 105### Step 1: Determine the doc type106 107| Feature Type        | Doc Location                                        | Template         |108| ------------------- | --------------------------------------------------- | ---------------- |109| New component       | `docs/01-app/03-api-reference/02-components/`       | API Reference    |110| New function        | `docs/01-app/03-api-reference/04-functions/`        | API Reference    |111| New config option   | `docs/01-app/03-api-reference/05-config/`           | Config Reference |112| New concept/guide   | `docs/01-app/02-guides/`                            | Guide            |113| New file convention | `docs/01-app/03-api-reference/03-file-conventions/` | File Convention  |114 115### Step 2: Create the file with proper naming116 117- Use kebab-case: `my-new-feature.mdx`118- Add numeric prefix if ordering matters: `05-my-new-feature.mdx`119- Place in the correct directory based on feature type120 121### Step 3: Use the appropriate template122 123**API Reference Template:**124 125```mdx126---127title: Feature Name128description: Brief description of what this feature does.129---130 131{/* 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. */}132 133Brief introduction to the feature.134 135## Reference136 137### Props138 139<div style={{ overflowX: 'auto', width: '100%' }}>140 141| Prop                    | Example            | Type   | Status   |142| ----------------------- | ------------------ | ------ | -------- |143| [`propName`](#propname) | `propName="value"` | String | Required |144 145</div>146 147#### `propName`148 149Description of the prop.150 151\`\`\`tsx filename="app/example.tsx" switcher152// TypeScript example153\`\`\`154 155\`\`\`jsx filename="app/example.js" switcher156// JavaScript example157\`\`\`158```159 160**Guide Template:**161 162```mdx163---164title: How to do X in Next.js165nav_title: X166description: Learn how to implement X in your Next.js application.167---168 169Introduction explaining why this guide is useful.170 171## Prerequisites172 173What the reader needs to know before starting.174 175## Step 1: First Step176 177Explanation and code example.178 179\`\`\`tsx filename="app/example.tsx" switcher180// Code example181\`\`\`182 183## Step 2: Second Step184 185Continue with more steps...186 187## Next Steps188 189Related topics to explore.190```191 192### Step 4: Add related links193 194Update frontmatter with related documentation:195 196```yaml197related:198  title: Next Steps199  description: Learn more about related features.200  links:201    - app/api-reference/functions/related-function202    - app/guides/related-guide203```204 205## Documentation Conventions206 207See `references/DOC-CONVENTIONS.md` for complete formatting rules.208 209### Quick Reference210 211**Frontmatter (required):**212 213```yaml214---215title: Page Title (2-3 words)216description: One or two sentences describing the page.217---218```219 220**Code blocks:**221 222```223\`\`\`tsx filename="app/page.tsx" switcher224// TypeScript first225\`\`\`226 227\`\`\`jsx filename="app/page.js" switcher228// JavaScript second229\`\`\`230```231 232**Router-specific content:**233 234```mdx235<AppOnly>Content only for App Router docs.</AppOnly>236 237<PagesOnly>Content only for Pages Router docs.</PagesOnly>238```239 240**Notes:**241 242```mdx243> **Good to know**: Single line note.244 245> **Good to know**:246>247> - Multi-line note point 1248> - Multi-line note point 2249```250 251## Validation Checklist252 253Before committing documentation changes:254 255- [ ] Frontmatter has `title` and `description`256- [ ] Code blocks have `filename` attribute257- [ ] TypeScript examples use `switcher` with JS variant258- [ ] Props tables are properly formatted259- [ ] Related links point to valid paths260- [ ] `pnpm lint` passes261- [ ] Changes render correctly (if preview available)262 263## References264 265- `references/DOC-CONVENTIONS.md` - Complete frontmatter and formatting rules266- `references/CODE-TO-DOCS-MAPPING.md` - Source code to documentation mapping267