文档贡献指南

欢迎来到 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 提供智能感知和语法高亮。
• Prettier：保存时自动格式化 MDX 文件。

审核流程

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

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

提示：提交 PR 前运行 pnpm prettier-fix 以运行 Prettier。

文件结构

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

文件结构反映了您在网站上看到的导航，默认情况下导航项按字母顺序排序。但我们可以通过在文件夹或文件名前添加两位数编号（00-）来更改排序顺序。

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

04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...

而在 路由部分，文件以两位数编号为前缀，按开发者应学习这些概念的顺序排序：

01-routing
├── 01-defining-routes.mdx
├── 02-pages.mdx
├── 03-layouts-and-templates.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
version: experimental
---

App 和 Pages 文档

由于 App 路由 (App Router) 和 Pages 路由 (Pages Router) 中的大多数功能完全不同，它们的文档分别保存在不同部分（02-app 和 03-pages）。但有一些功能是两者共享的。

共享页面

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

---
title: <Link>
description: <Link> 组件的 API 参考。
---

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

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

{/* 请勿编辑此页面。 */}
{/* 此页面内容来自上述源文件。 */}

这样，我们只需在一处编辑内容，即可在两个部分中反映出来。

共享内容

在共享页面中，有时可能会有 App 路由 或 Pages 路由 特有的内容。例如，<Link> 组件有一个 shallow 属性，仅在 Pages 中可用，而在 App 中不可用。

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

此内容在 App 和 Pages 之间共享。

<PagesOnly>

此内容仅在 Pages 文档中显示。

</PagesOnly>

此内容在 App 和 Pages 之间共享。

您可能会在示例和代码块中使用这些组件。

代码块

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

例如，如果要展示如何使用 <Link> 组件，应包括 import 语句和 <Link> 组件本身。

import Link from 'next/link'

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

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

语言和文件名

代码块应包含语言和 filename 的标题。添加 filename 属性会渲染一个特殊的终端图标，帮助用户定位输入命令的位置。例如：

```bash filename="Terminal"
npx create-next-app
```

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

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

须知：

• 确保在 JavaScript 文件中使用 js 扩展名与 JSX 代码。
• 例如：```jsx filename="app/layout.js"

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">About</Link>
}

多行： highlight={1,3}

import Link from 'next/link'

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

行范围： highlight={1-5}

import Link from 'next/link'

export default function Page() {
  return <Link href="/about">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 页面应在页面底部提供概述表格，并尽可能包含跳转链接。
• 下一步（相关链接）：添加相关页面链接以引导用户的学习路径。

根据需要自由添加这些部分。

页面类型

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

• 概念性页面用于解释某个概念或功能，通常篇幅较长且包含更多信息。在 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 社区的一员！