文档贡献指南
了解如何为 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 文件中:
{
"files.associations": {
"*.mdx": "markdown"
}
}接下来,再次打开命令面板,搜索 Markdown: Preview File 或 Markdown: Open Preview to the Side。这将打开一个预览窗口,你可以在其中查看格式化后的更改。
扩展#
我们还推荐 VSCode 用户使用以下扩展:
审核流程#
提交贡献后,Next.js 团队或开发者体验团队将审核你的更改、提供反馈,并在准备就绪时合并 pull request。
如果你有任何问题或需要进一步帮助,请在 PR 评论中告诉我们。感谢你为 Next.js 文档做贡献,并成为我们社区的一员!
提示: 在提交 PR 前运行
pnpm prettier-fix以运行 Prettier。
文件结构#
文档使用文件系统路由。/docs 中的每个文件夹和文件都代表一个路由段。这些段用于生成 URL 路径、导航和面包屑。
文件结构反映了你在网站上看到的导航,默认情况下导航项按字母顺序排序。不过,我们可以通过在文件夹或文件名前添加两位数字(00-)来更改条目顺序。
例如,在 functions API 参考中,页面按字母顺序排列,因为这样开发者更容易找到特定函数:
04-functions
├── after.mdx
├── cacheLife.mdx
├── cacheTag.mdx
└── ...但是,在 app router 部分中,文件以两位数字为前缀,按照开发者应学习这些概念的顺序排序:
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"> 标签。 |
---
title: 页面标题
description: 页面描述
---良好的做法是将页面标题限制为 2-3 个词(例如“优化图片”),将描述限制为 1-2 句话(例如“了解如何在 Next.js 中优化图片”)。
可选字段#
以下字段是可选的:
| 字段 | 描述 |
|---|---|
nav_title | 覆盖导航中的页面标题。当页面标题太长无法显示时很有用。如果未提供,则使用 title 字段。 |
source | 将内容拉取到共享页面中。请参阅共享页面。 |
related | 文档底部的相关页面列表。这些链接会自动转换为卡片。请参阅相关链接。 |
version | 开发阶段,例如 experimental、legacy、unstable、RC。 |
---
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 中:
---
title: <Link>
description: <Link> 组件的 API 参考。
---
本 API 参考将帮助你了解如何使用 Link 组件可用的 props
和配置选项。---
title: <Link>
description: <Link> 组件的 API 参考。
source: app/api-reference/components/link
---
因此,我们可以在一个地方编辑内容,并让它同时反映在两个部分中。
共享内容#
在共享页面中,有时会有特定于 App Router 或 Pages Router 的内容。例如,<Link> 组件有一个 shallow prop,它仅在 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 的头部。例如:
```tsx filename="app/page.tsx"
export default function Page() {
return <h1>Hello, Next.js!</h1>
}
对于 CLI 命令,使用 `package` prop 显示每个包管理器的命令:
````mdx filename="code-example.mdx"
```bash package="pnpm"
pnpm create next-appnpx create-next-app@latestyarn create next-appbun create next-app
文档中的大多数示例使用 `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
> **小知识**:我们计划在未来自动将 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}
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
---嵌套字段#
| 字段 | 必填? | 描述 |
|---|---|---|
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 社区的一员!