NNext.js 中文网 GitHub

文档贡献指南

了解如何为 Next.js 文档做贡献

欢迎阅读 Next.js 文档贡献指南!很高兴你来到这里。

本页介绍如何编辑 Next.js 文档。我们的目标是让社区中的每个人都能放心地参与贡献并改进文档。

为什么要贡献?#

开源工作永无止境,文档也是如此。贡献文档是初学者参与开源的好方式,也让有经验的开发者能够澄清更复杂的话题,同时与社区分享知识。

通过为 Next.js 文档做贡献,你是在帮助我们为所有开发者构建更健壮的学习资源。无论是发现了拼写错误、令人困惑的章节,还是意识到缺少某个主题,我们都欢迎并感谢你的贡献。

如何贡献#

文档内容位于 Next.js 仓库中。要贡献内容,你可以直接在 GitHub 上编辑文件,也可以克隆仓库并在本地编辑文件。

GitHub 工作流#

如果你刚接触 GitHub,建议阅读 GitHub 开源指南,了解如何 fork 仓库、创建分支和提交 pull request。

小知识:底层文档代码位于一个私有代码库中,并同步到 Next.js 公共仓库。这意味着你无法在本地预览文档。不过,在合并 pull request 后,你将在 nextjs.org 上看到你的更改。

编写 MDX#

文档使用 MDX 编写,这是一种支持 JSX 语法的 markdown 格式。这使我们能够在文档中嵌入 React 组件。有关 markdown 语法的快速概览,请参阅 GitHub Markdown 指南。

VSCode#

在本地预览更改#

VSCode 内置了 markdown 预览器,你可以用它查看本地编辑效果。要为 MDX 文件启用预览器,你需要在用户设置中添加一个配置项。

打开命令面板(Mac 上是 ⌘ + ⇧ + P,Windows 上是 Ctrl + Shift + P),搜索 Preferences: Open User Settings (JSON)。

然后,将以下行添加到你的 settings.json 文件中:

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

接下来,再次打开命令面板,搜索 Markdown: Preview File 或 Markdown: Open Preview to the Side。这将打开一个预览窗口,你可以在其中查看格式化后的更改。

扩展#

我们还推荐 VSCode 用户使用以下扩展:

  • MDX:MDX 的智能感知和语法高亮。
  • Prettier:保存时格式化 MDX 文件。

审核流程#

提交贡献后,Next.js 团队或开发者体验团队将审核你的更改、提供反馈,并在准备就绪时合并 pull request。

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

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

文件结构#

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

文件结构反映了你在网站上看到的导航,默认情况下导航项按字母顺序排序。不过,我们可以通过在文件夹或文件名前添加两位数字(00-)来更改条目顺序。

例如,在 functions API 参考中,页面按字母顺序排列,因为这样开发者更容易找到特定函数:

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

但是,在 app router 部分中,文件以两位数字为前缀,按照开发者应学习这些概念的顺序排序:

txt
01-getting-started
├── 01-installation.mdx
├── 02-project-structure.mdx
├── 03-layouts-and-pages.mdx
└── ...

要快速查找页面,可以使用 ⌘ + P(Mac)或 Ctrl + P(Windows)打开 VSCode 的搜索栏。然后,输入你要查找页面的 slug,例如 installation。

为什么不使用清单文件?

我们考虑过使用清单文件(另一种生成文档导航的常见方式),但发现清单很快就会与文件失去同步。文件系统路由迫使我们思考文档的结构,并且对 Next.js 来说感觉更原生。

元数据#

每个页面在文件顶部都有一个由三个短横线分隔的元数据块。

必填字段#

以下字段是必填的:

字段描述
title页面的 <h1> 标题,用于 SEO 和 OG 图片。
description页面的描述,用于 SEO 的 <meta name="description"> 标签。
required-fields.mdx
---
title: 页面标题
description: 页面描述
---

良好的做法是将页面标题限制为 2-3 个词(例如“优化图片”),将描述限制为 1-2 句话(例如“了解如何在 Next.js 中优化图片”)。

可选字段#

以下字段是可选的:

字段描述
nav_title覆盖导航中的页面标题。当页面标题太长无法显示时很有用。如果未提供,则使用 title 字段。
source将内容拉取到共享页面中。请参阅共享页面。
related文档底部的相关页面列表。这些链接会自动转换为卡片。请参阅相关链接。
version开发阶段,例如 experimental、legacy、unstable、RC。
optional-fields.mdx
---
nav_title: 导航项标题
source: app/building-your-application/optimizing/images
related:
  description: 请参阅图片组件 API 参考。
  links:
    - app/api-reference/components/image
version: experimental
---

App 和 Pages 文档#

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

共享页面#

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

app/.../link.mdx
---
title: <Link>
description: <Link> 组件的 API 参考。
---

本 API 参考将帮助你了解如何使用 Link 组件可用的 props
和配置选项。
pages/.../link.mdx
---
title: <Link>
description: <Link> 组件的 API 参考。
source: app/api-reference/components/link
---


因此,我们可以在一个地方编辑内容,并让它同时反映在两个部分中。

共享内容#

在共享页面中,有时会有特定于 App Router 或 Pages Router 的内容。例如,<Link> 组件有一个 shallow prop,它仅在 Pages 中可用,而在 App 中不可用。

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

app/.../link.mdx
此内容在 App 和 Pages 之间共享。

<PagesOnly>

此内容只会在 Pages 文档中显示。

</PagesOnly>

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

你很可能会将这些组件用于示例和代码块。

代码块#

代码块应包含可复制粘贴的最小可运行示例。这意味着代码应能在无需任何额外配置的情况下运行。

例如,如果你展示如何使用 <Link> 组件,应包含 import 语句和 <Link> 组件本身。

app/page.tsx
import Link from 'next/link'

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

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

语言和文件名#

代码块应有一个包含语言和 filename 的头部。例如:

code-example.mdx
```tsx filename="app/page.tsx"
export default function Page() {
  return <h1>Hello, Next.js!</h1>
}
text

对于 CLI 命令,使用 `package` prop 显示每个包管理器的命令:

````mdx filename="code-example.mdx"
```bash package="pnpm"
pnpm create next-app
bash · npm
npx create-next-app@latest
bash · yarn
yarn create next-app
bash · bun
bun create next-app
text

文档中的大多数示例使用 `tsx` 和 `jsx` 编写,少数使用 `bash`。不过,你可以使用任何受支持的语言,这里是[完整列表](https://s.nodejs.cn/8ceb288b-0ee2-4933-a830-98d98712e5ed)。

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

|                             | 语言     | 扩展名 |
| --------------------------- | -------- | ------ |
| 包含 JSX 代码的 JavaScript 文件 | ` ```jsx ` | .js    |
| 不包含 JSX 的 JavaScript 文件   | ` ```js `  | .js    |
| 包含 JSX 的 TypeScript 文件     | ` ```tsx ` | .tsx   |
| 不包含 JSX 的 TypeScript 文件   | ` ```ts `  | .ts    |

> **小知识**:
>
> - 对于包含 **JSX** 代码的 JavaScript 文件,请务必使用 **`.js`** 扩展名。
> - 例如,` ```jsx filename="app/layout.js" `

### TS 和 JS 切换器

添加语言切换器,以便在 TypeScript 和 JavaScript 之间切换。代码块应先写 TypeScript,再提供 JavaScript 版本,以照顾更多用户。

目前,我们一个接一个地编写 TS 和 JS 示例,并使用 `switcher` prop 将它们链接起来:

````mdx filename="code-example.mdx"
```tsx filename="app/page.tsx" switcher
app/page.js
text

> **小知识**:我们计划在未来自动将 TypeScript 片段编译为 JavaScript。在此之前,你可以使用 [transform.tools](https://s.nodejs.cn/3a2d81c3-6c2c-47d6-8f7e-ef8cf7784870)。

### 行高亮

可以高亮代码行。当你想引导读者注意代码的特定部分时,这很有用。你可以通过向 `highlight` prop 传递数字来高亮行。

**单行:** `highlight={1}`

```tsx filename="app/page.tsx" {1}
import Link from 'next/link'

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

多行: highlight={1,3}

app/page.tsx
import Link from 'next/link'

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

行范围: highlight={1-5}

app/page.tsx
import Link from 'next/link'

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

图标#

文档中可使用以下图标:

mdx-icon.mdx
<Check size={18} />
<Cross size={18} />

输出:

我们不在文档中使用表情符号。

提示#

对于重要但不关键的信息,使用提示。提示是一种添加信息而不会让用户从主要内容分心的方式。

notes.mdx
> **小知识**:这是一行提示。

> **小知识**:
>
> - 我们也用这种格式编写多行提示。
> - 有时会有多个值得了解或需要记住的事项。

输出:

小知识:这是一行提示。

小知识:

  • 我们也用这种格式编写多行提示。
  • 有时会有多个值得了解或需要记住的事项。

相关链接#

相关链接通过指向符合逻辑的下一步的链接来引导用户的学习旅程。

  • 链接将显示在页面主要内容下方的卡片中。
  • 有子页面的页面会自动生成链接。

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

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

嵌套字段#

字段必填?描述
title可选卡片列表的标题。默认为 后续步骤。
description可选卡片列表的描述。
links必填指向其他文档页面的链接列表。每个列表项应为相对 URL 路径(不带前导斜杠),例如 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 文档中,概念型页面位于 构建你的应用 部分。
  • 参考型页面用于解释特定 API。它们通常更短、更聚焦。在 Next.js 文档中,参考型页面位于 API 参考 部分。

小知识:根据你所贡献的页面,你可能需要遵循不同的语气和风格。例如,概念型页面更具指导性,使用“你”(you)来称呼用户。参考型页面更技术化,使用更多祈使词,如“create、update、accept”,并且往往省略 you。

语气#

以下是一些指南,帮助你在文档中保持一致的风格和语气:

  • 写清晰、简洁的句子。避免离题。
    • 如果你发现自己用了很多逗号,考虑把句子拆成多个句子或使用列表。
    • 用更简单的词替换复杂词。例如,用 use 代替 utilize。
  • 注意 this 这个词。它可能含糊不清,令人困惑,如果不清楚,不要害怕重复句子的主语。
    • 例如,用 Next.js uses React 而不是 Next.js uses this。
  • 使用主动语态而不是被动语态。主动句更易读。
    • 例如,用 Next.js uses React 而不是 React is used by Next.js。如果你发现自己使用 was 和 by 之类的词,可能正在使用被动语态。
  • 避免使用 easy、quick、simple、just 等词。这些词很主观,可能会让用户感到气馁。
  • 避免使用 don't、can't、won't 等否定词。这可能会让读者感到气馁。
    • 例如,用“你可以使用 Link 组件在页面之间创建链接”而不是“不要使用 <a> 标签在页面之间创建链接”。
  • 使用第二人称(you/your)。这更个人化,也更有吸引力。
  • 使用性别中立的语言。指代受众时使用 developers、users 或 readers。
  • 如果添加代码示例,请确保其格式正确且可运行。

虽然这些指南并不详尽,但它们应该能帮助你入门。如果你想深入了解技术写作,请查看 Google 技术写作课程。


感谢你为文档做贡献,并成为 Next.js 社区的一员!

Next.js 中文网