update-docs

Files (3)

• SKILL.md
• CODE-TO-DOCS-MAPPING.md · references/
• DOC-CONVENTIONS.md · references/

SKILL.md (first lines)

# 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
# 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:

| Source Path                            | Likely Doc Impact           |
| -------------------------------------- | --------------------------- |
| `packages/next/src/client/components/` | Component API reference     |
| `packages/next/src/server/`            | Function API reference      |
| `packages/next/src/shared/lib/`        | Varies by export            |
| `packages/next/src/build/`             | Configuration or build docs |
| `packages/next/src/lib/`               | Various features            |

### 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
# 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

```bash
pnpm lint          # Check formatting
pnpm 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

| Feature Type        | Doc Location                                        | Template         |
| ------------------- | --------------------------------------------------- | ---------------- |
| New component       | `docs/01-app/03-api-reference/02-components/`       | API Reference    |
| New function        | `docs/01-app/03-api-reference/04-functions/`        | API Reference    |
| New config option   | `docs/01-app/03-api-reference/05-config/`           | Config Reference |
| New concept/guide   | `docs/01-app/02-guides/`                            | Guide            |
| New file convention | `docs/01-app/03-api-reference/03-file-conventions/` | File Convention  |

### 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
---

From evgeshniyzik-dev/nextjs, MIT.

More from evgeshniyzik-dev/nextjs