Sponsor
ntab.devntab.dev —提升效率的新标签页组件
点击查看
Menu

文档贡献指南

欢迎来到 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 文件中：

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
└── ...

要快速找到一个页面，你可以使用 ⌘ + P（Mac）或 Ctrl + P（Windows）在 VSCode 上打开搜索栏。然后，输入你要查找的页面的 slug。例如 defining-routes

为什么不使用清单？

我们考虑使用清单文件（另一种生成文档导航的流行方式），但我们发现清单很快就会与文件不同步。文件系统路由强制我们思考文档的结构，并且感觉更符合 Next.js 的原生特性。

元数据

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

必填字段

以下字段是必填的：

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

最好将页面标题限制为 2-3 个单词（例如 Optimizing Images）和描述限制为 1-2 个句子（例如 Learn how to optimize images in Next.js）。

可选字段

以下字段是可选的：

字段描述
nav_title覆盖导航中页面的标题。当页面标题太长而无法适应时，这很有用。如果未提供，则使用 title 字段。
source将内容拉入共享页面。请参阅共享页面。
related文档底部的相关页面列表。这些将自动转换为卡片。请参阅相关链接。
version开发阶段。例如 experimental、legacy、unstable、RC
optional-fields.mdx
---
nav_title: 导航项标题
source: /docs/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: /docs/app/api-reference/components/link
---
 
{/* 请勿编辑此页面。 */}
{/* 此页面的内容从上面的 source 中提取。 */}

因此，我们可以在一个地方编辑内容，并使其反映在两个部分中。

共享内容

在共享页面中，有时可能会有 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 的头部。添加 filename 属性可以渲染一个特殊的终端图标，帮助用户确定在哪里输入命令。例如：

code-example.mdx
```bash filename="Terminal"
npx create-next-app
```

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

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

语言扩展
带有 JSX 代码的 JavaScript 文件```jsx.js
不带 JSX 的 JavaScript 文件```js.js
带有 JSX 的 TypeScript 文件```tsx.tsx
不带 JSX 的 TypeScript 文件```ts.ts

值得注意的是：

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

TS 和 JS 切换器

添加语言切换器以在 TypeScript 和 JavaScript 之间切换。代码块应该首先是 TypeScript，再提供 JavaScript 版本以适应用户。

目前，我们一个接一个地编写 TS 和 JS 示例，并通过 switcher 属性链接它们：

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

值得注意的是：我们计划在未来自动将 TypeScript 片段编译为 JavaScript。在此期间，你可以使用 transform.tools。

行高亮

代码行可以高亮显示。当你想要引起对代码特定部分的注意时，这很有用。你可以通过将数字传递给 highlight 属性来高亮显示行。

单行： highlight={1}

app/page.tsx
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可选卡片列表的标题。默认为 Next Steps。
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 来称呼用户。参考页面更技术性，它们使用更多的命令式词如"创建、更新、接受"，并倾向于省略单词 you。

语气

以下是在文档中保持一致风格和语气的一些指南：

  • 写清晰、简洁的句子。避免离题。
    • 如果你发现自己使用了很多逗号，考虑将句子分成多个句子或使用列表。
    • 用简单的词代替复杂的词。例如，用 use 而不是 utilize。
  • 注意单词 this。它可能含糊不清，如果不清楚，不要害怕重复句子的主语。
    • 例如，用 Next.js 使用 React 而不是 Next.js 使用这个。
  • 使用主动语态而不是被动语态。主动句子更容易阅读。
    • 例如，用 Next.js 使用 React 而不是 React 被 Next.js 使用。如果你发现自己使用了 was 和 by 等词，你可能正在使用被动语态。
  • 避免使用像 easy、quick、simple、just 等词。这是主观的，可能会让用户感到气馁。
  • 避免使用否定词如 don't、can't、won't 等。这可能会让读者感到气馁。
    • 例如，用 "你可以使用 Link 组件在页面之间创建链接" 而不是 "不要使用 <a> 标签在页面之间创建链接"。
  • 使用第二人称（你/你的）。这更个人化和吸引人。
  • 使用性别中立的语言。在指代受众时使用 开发者、用户 或 读者。
  • 如果添加代码示例，确保它们格式正确且可以工作。

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

感谢你为文档做出贡献并成为 Next.js 社区的一部分！