文档贡献指南

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

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

为什么要贡献？

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

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

如何贡献

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

GitHub 工作流

如果您是 GitHub 新手，建议阅读 GitHub 开源指南，了解如何 fork 代码库、创建分支并提交拉取请求。

须知：文档底层代码位于私有代码库中，会同步到 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 路由 和 Pages 路由 的大多数功能完全不同，它们的文档分别保存在不同部分（02-app 和 03-pages）。但有些功能是两者共享的。

共享页面

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

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

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

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

{/* 请勿编辑此页面 */}
{/* 此页面内容来自上方 source 字段指定的源 */}

这样我们只需在一处编辑内容，两处都会更新。

共享内容

在共享页面中，有时可能有仅适用于 App 路由 或 Pages 路由 的内容。例如 <Link> 组件的 shallow prop 仅在 Pages 中可用。

为确保内容只显示在正确的路由文档中，我们可以用 <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">关于</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 页面应在页面底部提供概览表格（可能时包含跳转链接）
• 下一步（相关链接）：添加相关页面链接以引导用户学习路径

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

页面类型

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

• 概念性 页面用于解释某个概念或功能。它们通常篇幅较长，包含的信息比参考页面更丰富。在 Next.js 文档中，概念性页面位于 构建应用 (Building Your Application) 部分。
• 参考性 页面用于说明特定 API。它们通常更简短且针对性更强。在 Next.js 文档中，参考性页面位于 API 参考 (API Reference) 部分。

小提示：根据您贡献的页面类型，可能需要采用不同的语气和风格。例如，概念性页面更具指导性，会使用“您”来称呼用户；而参考性页面更偏技术性，会使用更多命令式词汇（如“创建、更新、接受”），并倾向于省略“您”这个词。

写作风格

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

• 撰写清晰简洁的句子，避免跑题。
  • 如果发现句子中使用了很多逗号，可以考虑拆分成多个句子或改用列表形式。
  • 用简单词汇替代复杂词汇，例如用“使用”而非“利用 (utilize)”。
• 慎用“这 (this)”字。它可能指代不清，如果语义不明，请大胆重复主语。
  • 例如：“Next.js 使用 React”优于“Next.js 使用这个”。
• 使用主动语态而非被动语态。主动句更易阅读。
  • 例如：“Next.js 使用 React”优于“React 被 Next.js 使用”。如果发现使用了“被 (was/by)”等词，可能正在使用被动语态。
• 避免使用“简单 (easy)”、“快速 (quick)”、“只需 (just)”等主观词汇，这可能让用户感到挫败。
• 避免“不要 (don't)”、“不能 (can't)”、“不会 (won't)”等否定词汇，这可能让读者沮丧。
  • 例如：“您可以使用 Link 组件创建页面链接”优于“不要用 <a> 标签创建页面链接”。
• 使用第二人称（你/您），这样更亲切且具有代入感。
• 使用性别中立语言。提及受众时使用“开发者 (developers)”、“用户 (users)”或“读者 (readers)”。
• 如果添加代码示例，请确保格式正确且可运行。

虽然这些指南并不全面，但能帮助您快速入门。如果想深入学习技术写作，请参考 Google 技术写作课程。

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