文档贡献指南

欢迎阅读 Next.js 文档贡献指南！我们很高兴您的加入。

本页面提供了编辑 Next.js 文档的指导说明。我们的目标是让社区中的每个人都能轻松参与并改进文档。

为何贡献？

开源工作永无止境，文档亦是如此。贡献文档是初学者参与开源的好方式，也是经验丰富的开发者分享知识、澄清复杂概念的机会。

通过为 Next.js 文档做贡献，您正在帮助我们为所有开发者构建更强大的学习资源。无论是发现拼写错误、难以理解的章节，还是意识到某个主题缺失，您的贡献都备受欢迎和赞赏。

如何贡献

文档内容位于 Next.js 代码库。您可以直接在 GitHub 上编辑文件，或克隆代码库后在本地修改。

GitHub 工作流

如果您是 GitHub 新手，建议阅读 GitHub 开源指南 了解如何复刻仓库、创建分支和提交拉取请求。

须知：文档底层代码存放在私有代码库中，会同步到 Next.js 公共仓库。这意味着您无法在本地预览文档变更，但合并拉取请求后可以在 nextjs.org 看到修改效果。

编写 MDX

文档采用 MDX 格式编写，这是一种支持 JSX 语法的 Markdown 格式。这使得我们能在文档中嵌入 React 组件。请参阅 GitHub Markdown 指南 快速了解 Markdown 语法。

VSCode 配置

本地预览修改

VSCode 内置了 Markdown 预览器，可用于本地查看编辑效果。要为 MDX 文件启用预览器，需在用户设置中添加配置项。

打开命令面板（Mac 使用 ⌘ + ⇧ + P，Windows 使用 Ctrl + Shift + P），搜索 Preferences: Open User Settings (JSON)。

然后在 settings.json 文件中添加以下内容：

{
  "files.associations": {
    "*.mdx": "markdown"
  }
}

再次打开命令面板，搜索 Markdown: Preview File 或 Markdown: Open Preview to the Side，这将打开预览窗口显示格式化后的内容。

推荐扩展

我们为 VSCode 用户推荐以下扩展：

• MDX：提供 MDX 的智能提示和语法高亮
• Grammarly：语法和拼写检查工具
• Prettier：保存时自动格式化 MDX 文件

审核流程

提交贡献后，Next.js 或开发者体验团队将审核您的修改，提供反馈并在准备就绪时合并拉取请求。

如有任何问题或需要进一步帮助，请在 PR 评论中告知我们。感谢您为 Next.js 文档做出贡献并成为我们社区的一员！

提示：提交 PR 前可运行 pnpm prettier-fix 执行 Prettier 格式化。

文件结构

文档采用文件系统路由。每个文件夹和 /docs 内的文件代表一个路由段，用于生成 URL 路径、导航和面包屑导航。

文件结构反映网站导航，默认情况下导航项按字母顺序排序。但我们可以通过在文件夹或文件名前添加两位数编号 (00-) 来调整顺序。

例如在 函数 API 参考 中，页面按字母排序便于开发者查找特定函数：

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

而在 路由章节 中，文件添加了两位数前缀，按学习顺序排列：

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.mdx
└── ...

要快速定位页面，可在 VSCode 中使用 ⌘ + P (Mac) 或 Ctrl + P (Windows) 打开搜索栏，输入页面 slug。例如 defining-routes

为何不使用清单文件？

我们考虑过使用清单文件（另一种流行的文档导航生成方式），但发现清单容易与文件不同步。文件系统路由迫使我们思考文档结构，也更符合 Next.js 的原生特性。

元数据

每个文件顶部都有一个由三个破折号分隔的元数据块。

必填字段

以下字段为必填项：

---
title: 页面标题
description: 页面描述
---

最佳实践是将标题限制在 2-3 个词（如"图片优化"），描述控制在 1-2 句话（如"学习如何在 Next.js 中优化图片"）。

可选字段

以下字段为可选项：

---
nav_title: 导航项标题
source: app/building-your-application/optimizing/images
related:
  description: 查看图片组件 API 参考。
  links:
    - app/api-reference/components/image
---

App 与 Pages 文档

由于应用路由 (App Router) 和页面路由 (Pages Router) 的大多数功能完全不同，它们的文档分别存放在不同章节 (02-app 和 03-pages)。但有些功能是两者共用的。

共享页面

为避免内容重复和不同步风险，我们使用 source 字段将内容从一个页面拉取到另一个页面。例如 <Link> 组件在应用和页面中的行为基本一致，我们可以从 app/.../link.mdx 拉取内容到 pages/.../link.mdx：

---
title: <Link>
description: 关于 <Link> 组件的 API 参考文档。
---

本 API 参考将帮助您理解如何使用 Link 组件的属性和配置选项。

---
title: <Link>
description: 关于 <Link> 组件的 API 参考文档。
source: app/api-reference/components/link
---

{/* 请勿编辑本页面 */}
{/* 本页面内容来自上方源文件 */}

这样我们只需在一处编辑内容，变更就会同步到两个章节。

共享内容

在共享页面中，有时可能需要区分应用路由或页面路由特有的内容。例如 <Link> 组件的 shallow 属性仅在页面路由中可用。

为确保内容只显示在正确的路由文档中，我们可以用 <AppOnly> 或 <PagesOnly> 组件包裹内容块：

此内容在应用和页面路由中共享。

<PagesOnly>

此内容仅显示在页面路由文档中。

</PagesOnly>

此内容在应用和页面路由中共享。

这些组件通常用于示例和代码块。

代码块

代码块应包含可复制粘贴的最小工作示例，确保无需额外配置即可运行。

例如展示 <Link> 组件用法时，应包含 import 语句和组件本身：

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">关于</Link>
}

提交前请务必在本地运行示例，确保代码是最新且可工作的。

语言与文件名

代码块应包含语言和 filename 的头部信息。添加 filename 属性会显示特殊的终端图标，帮助用户定位输入位置：

```bash filename="终端"
npx create-next-app
```

文档中大多数示例使用 tsx 和 jsx，少数使用 bash。但您可以使用任何支持的语言，完整列表参见 此处。

编写 JavaScript 代码块时，我们使用以下语言和扩展名组合：

TS 与 JS 切换器

添加语言切换器可在 TypeScript 和 JavaScript 间切换。代码块应优先提供 TypeScript 版本，同时包含 JavaScript 版本以满足不同用户需求。

目前我们依次编写 TS 和 JS 示例，并通过 switcher 属性关联：

```tsx filename="app/page.tsx" switcher

```

```jsx filename="app/page.js" switcher

```

须知：我们计划未来自动将 TypeScript 代码片段编译为 JavaScript。目前可使用 transform.tools 进行转换。

行高亮

可以高亮代码行以突出特定部分。通过向 highlight 属性传递数字实现高亮。

单行高亮：highlight={1}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">关于</Link>
}

多行高亮：highlight={1,3}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">关于</Link>
}

行范围高亮：highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">关于</Link>
}

图标

文档中可使用以下图标：

<Check size={18} />
<Cross size={18} />

效果：

文档中不使用表情符号。

注释

对于重要但非关键的信息，可使用注释。注释能添加信息而不分散用户对主要内容的注意力。

> **须知**：这是单行注释。

> **须知**：
>
> - 多行注释也采用此格式
> - 有时会有多个值得了解或注意的事项

效果：

须知：这是单行注释。

须知：

• 多行注释也采用此格式
• 有时会有多个值得了解或注意的事项

相关链接

相关链接通过添加逻辑后续步骤引导用户学习。

• 链接会以卡片形式显示在页面主要内容下方
• 对于有子页面的页面会自动生成链接。例如 优化 章节会显示所有子页面链接

使用页面元数据中的 related 字段创建相关链接：

---
related:
  description: 了解如何快速开始您的第一个应用。
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

嵌套字段

图表

图表是解释复杂概念的好方法。我们使用 Figma 创建图表，遵循 Vercel 设计指南。

当前图表存放在 Next.js 私有站点的 /public 文件夹中。如需更新或添加图表，请提交 GitHub issue。

自定义组件与 HTML

文档中可用的 React 组件包括：<Image /> (next/image)、<PagesOnly />、<AppOnly />、<Cross /> 和 <Check />。除 <details> 标签外，文档中不允许使用原始 HTML。

如有新组件想法，请提交 GitHub issue。

风格指南

本节为技术写作新手提供文档编写指南。

页面模板

虽然我们没有严格的页面模板，但文档中常见以下章节：

• 概述：首段应说明功能用途，随后提供最小工作示例或 API 参考
• 约定：如果功能有特殊约定，应在此说明
• 示例：展示不同使用场景下的功能用法
• API 表格：API 页面应在底部提供带跳转链接的概览表格（如适用）
• 后续步骤（相关链接）：添加相关页面链接引导用户学习路径

根据需要自由添加这些章节。

页面类型

文档页面分为两类：概念性文档和参考文档。

• 概念性文档用于解释某个概念或功能。这类文档通常篇幅较长，包含的信息比参考文档更丰富。在 Next.js 文档中，概念性文档位于构建应用 (Building Your Application) 部分。
• 参考文档用于说明具体的 API。这类文档通常更简短且专注。在 Next.js 文档中，参考文档位于API 参考 (API Reference) 部分。

须知：根据您贡献的文档类型，可能需要采用不同的语气和风格。例如，概念性文档更具指导性，会使用"您"来称呼读者；而参考文档则更技术化，会使用更多命令式词汇（如"创建、更新、接受"），并倾向于省略"您"这个词。

写作风格

以下指南有助于保持文档风格和语气的一致性：

• 撰写清晰简洁的句子，避免离题
  • 如果发现句子中使用了很多逗号，考虑将其拆分为多个句子或改用列表形式
  • 用简单词汇替代复杂词汇，例如用"使用"而非"利用"
• 谨慎使用"这"字，它可能造成歧义和困惑。如果指代不清，不要害怕重复主语
  • 例如："Next.js 使用 React"优于"Next.js 使用这个"
• 使用主动语态而非被动语态。主动句更易于阅读
  • 例如："Next.js 使用 React"优于"React 被 Next.js 使用"。如果发现使用了"被"、"由"等词，可能正在使用被动语态
• 避免使用"简单"、"快速"、"只需"等主观性词汇，这可能让用户感到沮丧
• 避免使用"不要"、"不能"、"不会"等否定性词汇，这可能打击读者积极性
  • 例如："您可以使用 Link 组件在页面间创建链接"优于"不要使用 <a> 标签在页面间创建链接"
• 使用第二人称（您/您的），这样更具亲和力
• 使用性别中立语言。提及受众时使用"开发者"、"用户"或"读者"
• 如果添加代码示例，请确保格式正确且可运行

虽然这些指南并不全面，但能帮助您快速入门。如需深入了解技术写作，请参阅Google 技术写作课程。

感谢您为文档做出贡献，成为 Next.js 社区的一员！