How to Streamline Next.js Documentation Updates with update-docs
When contributing to Next.js, documentation updates corresponding to code changes are often overlooked. Identifying which doc files need updating and understanding format rules takes effort.
This article explains how to efficiently update documentation based on code changes using the update-docs skill from the Next.js repository.
What This Skill Does
update-docs identifies documentation that needs updating based on Next.js code changes and guides the update process:
- Source code to documentation mapping (via CODE-TO-DOCS-MAPPING.md)
- Change analysis via
git diff - Existing doc updates or new feature doc scaffolding
- MDX format convention enforcement (frontmatter, code blocks, router-specific content)
Designed for developers contributing to Next.js core.
Installation
Prerequisites
- Claude Code installed
- Access to Next.js repository source code
Install Command
claude mcp add github.com/vercel/next.js/tree/canary/.claude/skills/update-docs
Usage
Basic Usage
After making code changes:
Update the docs for these code changes
The skill:
- Analyzes changes via
git diff canary...HEAD - Identifies corresponding doc files via CODE-TO-DOCS-MAPPING
- Highlights sections needing updates
- Applies MDX format conventions
Source-to-Doc Mapping
| Source Path | Documentation |
|---|---|
packages/next/src/client/components/ | Component API reference |
packages/next/src/server/ | Function API reference |
Documentation Conventions
- Frontmatter requires
titleanddescription - Code blocks need
filenameattribute andswitcherfor TS/JS variants - Router-specific content uses
<AppOnly>and<PagesOnly>components
pnpm lint
pnpm prettier-fix
Important Considerations
canary Branch Is the Baseline
Changes are analyzed against the canary branch, not main.
Strict MDX Formatting
Format rules for code block switchers and filename attributes are strictly enforced. The skill applies them automatically.
New Feature Doc Scaffolding
Beyond updating existing docs, the skill can scaffold documentation for entirely new features.
Summary
update-docs enables efficient Next.js documentation updates guided by code-to-doc mapping and format conventions. Use it to prevent documentation gaps during contributions.