update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Next.js Documentation Updater

Next.js 文档更新指南

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

指导你基于当前分支的代码变更更新Next.js文档，专为审核PR文档完整性的维护人员设计。

Quick Start

快速开始

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

分析变更：运行
```
git diff canary...HEAD --stat
```
查看变更的文件
确定受影响的文档：将变更的源文件映射到文档路径
审核每个文档：在用户确认后逐步完成更新
验证：运行
```
pnpm lint
```
检查格式
提交：暂存文档变更

Workflow: Analyze Code Changes

工作流：分析代码变更

Step 1: Get the diff

步骤1：获取差异

bash

undefined

bash

undefined

See all changed files on this branch

查看此分支上所有变更的文件

git diff canary...HEAD --stat

See changes in specific areas

查看特定区域的变更

git diff canary...HEAD -- packages/next/src/

undefined

git diff canary...HEAD -- packages/next/src/

undefined

Step 2: Identify documentation-relevant changes

步骤2：识别与文档相关的变更

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

重点关注以下区域的变更：

源文件路径	可能影响的文档类型
`packages/next/src/client/components/`	组件API参考文档
`packages/next/src/server/`	函数API参考文档
`packages/next/src/shared/lib/`	取决于导出内容
`packages/next/src/build/`	配置或构建相关文档
`packages/next/src/lib/`	各类功能文档

Step 3: Map to documentation files

步骤3：映射到文档文件

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/

使用

references/CODE-TO-DOCS-MAPPING.md

中的代码与文档映射关系，找到对应的文档文件。

示例映射：

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

步骤1：阅读当前文档

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

在进行变更前，先阅读现有文档以了解：

当前的结构和章节
使用的前置元数据字段
是否使用
```
<AppOnly>
```
/
```
<PagesOnly>
```
标记路由专属内容

Step 2: Identify what needs updating

步骤2：确定需要更新的内容

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

步骤3：在确认后应用更新

For each change:

Show the user what you plan to change
Wait for confirmation before editing
Apply the edit
Move to the next change

针对每个变更：

向用户展示计划的变更内容
等待用户确认后再编辑
应用编辑
处理下一个变更

Step 4: Check for shared content

步骤4：检查共享内容

If the doc uses the

source

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

yaml

undefined

如果文档使用

source

字段模式（Pages Router文档中常见），则需要编辑源文件而非当前文档。示例：

yaml

undefined

docs/02-pages/... file with shared content

docs/02-pages/... 包含共享内容的文件

source: app/building-your-application/optimizing/images


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

source: app/building-your-application/optimizing/images


编辑App Router的源文件，而非Pages Router的文件。

Step 5: Validate changes

步骤5：验证变更

bash

pnpm lint          # Check formatting
pnpm prettier-fix  # Auto-fix formatting issues

bash

pnpm lint          # 检查格式
pnpm prettier-fix  # 自动修复格式问题

Workflow: Scaffold New Feature Documentation

工作流：搭建新功能文档框架

Use this when adding documentation for entirely new features.

当为全新功能添加文档时使用此工作流。

Step 1: Determine the doc type

步骤1：确定文档类型

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

功能类型	文档位置	模板类型
新组件	`docs/01-app/03-api-reference/02-components/`	API参考文档
新函数	`docs/01-app/03-api-reference/04-functions/`	API参考文档
新配置选项	`docs/01-app/03-api-reference/05-config/`	配置参考文档
新概念/指南	`docs/01-app/02-guides/`	指南文档
新文件约定	`docs/01-app/03-api-reference/03-file-conventions/`	文件约定文档

Step 2: Create the file with proper naming

步骤2：以正确命名创建文件

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

使用短横线命名法：
```
my-new-feature.mdx
```
如果需要排序，添加数字前缀：
```
05-my-new-feature.mdx
```
根据功能类型放置到对应目录

Step 3: Use the appropriate template

步骤3：使用合适的模板

API Reference Template:

mdx

---
title: Feature Name
description: Brief description of what this feature does.
---

{/* 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. */}

Brief introduction to the feature.

API参考模板：

mdx

---
title: 功能名称
description: 此功能作用的简要说明。
---

{/* 本文档内容在App Router和Pages Router之间共享。你可以使用`<PagesOnly>内容</PagesOnly>`组件添加仅适用于Pages Router的内容。所有共享内容不应被组件包裹。 */}

功能简介。

Reference

参考

Props

属性

Prop	Example	Type	Status
`propName`	`propName="value"`	String	Required

</div>

属性	示例	类型	状态
`propName`	`propName="value"`	String	必填

</div>

propName

propName

Description of the prop.

```tsx filename="app/example.tsx" switcher // TypeScript example ```

```jsx filename="app/example.js" switcher // JavaScript example ```


**Guide Template:**

```mdx
---
title: How to do X in Next.js
nav_title: X
description: Learn how to implement X in your Next.js application.
---

Introduction explaining why this guide is useful.

属性说明。

```tsx filename="app/example.tsx" switcher // TypeScript示例 ```

```jsx filename="app/example.js" switcher // JavaScript示例 ```


**指南模板：**

```mdx
---
title: 如何在Next.js中实现X
nav_title: X
description: 学习如何在你的Next.js应用中实现X。
---

介绍此指南的用途。

Prerequisites

前置要求

What the reader needs to know before starting.

读者在开始前需要了解的内容。

Step 1: First Step

步骤1：第一步

Explanation and code example.

```tsx filename="app/example.tsx" switcher // Code example ```

说明和代码示例。

```tsx filename="app/page.tsx" switcher // 代码示例 ```

Step 2: Second Step

步骤2：第二步

Continue with more steps...

继续后续步骤...

Next Steps

下一步

Step 4: Add related links

步骤4：添加相关链接

Update frontmatter with related documentation:

yaml

related:
  title: Next Steps
  description: Learn more about related features.
  links:
    - app/api-reference/functions/related-function
    - app/guides/related-guide

更新前置元数据中的相关文档链接：

yaml

related:
  title: 下一步
  description: 了解更多相关功能。
  links:
    - app/api-reference/functions/related-function
    - app/guides/related-guide

Documentation Conventions

文档规范

See

references/DOC-CONVENTIONS.md

for complete formatting rules.

完整的格式规则请查看

references/DOC-CONVENTIONS.md

。

Quick Reference

快速参考

Frontmatter (required):

yaml

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

Code blocks:

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

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

Router-specific content:

mdx

<AppOnly>Content only for App Router docs.</AppOnly>

<PagesOnly>Content only for Pages Router docs.</PagesOnly>

Notes:

mdx

> **Good to know**: Single line note.

> **Good to know**:
>
> - Multi-line note point 1
> - Multi-line note point 2

必填前置元数据：

yaml

---
title: 页面标题（2-3个词）
description: 描述页面内容的1-2句话。
---

代码块：

\`\`\`tsx filename="app/page.tsx" switcher
// 先放TypeScript示例
\`\`\`

\`\`\`jsx filename="app/page.js" switcher
// 再放JavaScript示例
\`\`\`

路由专属内容：

mdx

<AppOnly>仅适用于App Router的文档内容。</AppOnly>

<PagesOnly>仅适用于Pages Router的文档内容。</PagesOnly>

注释：

mdx

> **小贴士**：单行注释。

> **小贴士**:
>
> - 多行注释要点1
> - 多行注释要点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)

提交文档变更前，请检查：

前置元数据包含
```
title
```
和
```
description
```
代码块包含
```
filename
```
属性
TypeScript示例搭配
```
switcher
```
和JavaScript版本
属性表格式正确
相关链接指向有效路径
```
pnpm lint
```
检查通过
变更渲染正常（如果有预览环境）

References

参考资料

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

```
references/DOC-CONVENTIONS.md
```
- 完整的前置元数据和格式规则
```
references/CODE-TO-DOCS-MAPPING.md
```
- 源代码与文档的映射关系