跳到内容
介绍社区贡献指南

文档贡献指南

欢迎来到 Next.js 文档贡献指南！我们很高兴您能来到这里。

本页面提供了关于如何编辑 Next.js 文档的说明。我们的目标是确保社区中的每个人都感到有能力贡献和改进我们的文档。

为何贡献？

开源工作永无止境，文档也是如此。为文档做贡献是初学者参与开源的好方法，也是经验丰富的开发者阐明更复杂主题，同时与社区分享知识的好方法。

通过为 Next.js 文档做贡献，您正在帮助我们为所有开发者构建更强大的学习资源。无论您是发现了一个错别字、一个令人困惑的部分，还是意识到缺少某个特定主题，我们都欢迎并感谢您的贡献。

如何贡献？

文档内容可以在 Next.js 仓库 中找到。要贡献内容，您可以直接在 GitHub 上编辑文件，或者克隆仓库并在本地编辑文件。

GitHub 工作流

如果您是 GitHub 新手，我们建议阅读 GitHub 开源指南，了解如何 fork 仓库、创建分支和提交 pull request。

须知：底层文档代码存在于一个私有代码库中，该代码库同步到 Next.js 公共仓库。这意味着您无法在本地预览文档。但是，在合并 pull request 后，您将在 nextjs.org 上看到您的更改。

编写 MDX

文档以 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 或开发者体验团队将审核您的更改，提供反馈，并在准备就绪后合并 pull request。

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

提示： 运行 pnpm prettier-fix 以在提交 PR 之前运行 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页面的描述，用于 SEO 的 <meta name="description"> 标签中。
required-fields.mdx
---
title: Page Title
description: Page Description
---

最佳实践是将页面标题限制为 2-3 个单词（例如：优化图像），并将描述限制为 1-2 句话（例如：了解如何在 Next.js 中优化图像）。

可选字段

以下字段为 可选

字段描述
nav_title覆盖页面在导航栏中的标题。当页面标题太长而无法容纳时，这很有用。如果未提供，则使用 title 字段。
source将内容拉入共享页面。请参阅 共享页面。
related文档底部的相关页面列表。这些将自动转换为卡片。请参阅 相关链接。
version开发阶段。例如：experimental、legacy、unstable、RC
optional-fields.mdx
---
nav_title: Nav Item Title
source: app/building-your-application/optimizing/images
related:
  description: See the image component API reference.
  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: API reference for the <Link> component.
---
 
This API reference will help you understand how to use the props
and configuration options available for the Link Component.
pages/.../link.mdx
---
title: <Link>
description: API reference for the <Link> component.
source: app/api-reference/components/link
---
 
{/* DO NOT EDIT THIS PAGE. */}
{/* The content of this page is pulled from the source above. */}

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

共享内容

在共享页面中，有时可能存在 App Router 或 Pages Router 特定的内容。例如，<Link> 组件具有一个 shallow prop，该 prop 仅在 Pages 中可用，但在 App 中不可用。

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

app/.../link.mdx
This content is shared between App and Pages.
 
<PagesOnly>
 
This content will only be shown on the Pages docs.
 
</PagesOnly>
 
This content is shared between App and 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 文件中对 JSX 代码使用 js 扩展名。
  • 例如，```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
> **Good to know**: This is a single line note.
 
> **Good to know**:
>
> - We also use this format for multi-line notes.
> - There are sometimes multiple items worth knowing or keeping in mind.

输出

须知: 这是一个单行备注。

须知:

  • 我们也将此格式用于多行备注。
  • 有时有多个项目值得了解或牢记。

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

  • 链接将显示在页面主要内容下方的卡片中。
  • 对于具有子页面的页面，链接将自动生成。例如，“Optimizing”部分包含指向其所有子页面的链接。

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

example.mdx
---
related:
  description: Learn how to quickly get started with your first application.
  links:
    - app/building-your-application/routing/defining-routes
    - app/building-your-application/data-fetching
    - app/api-reference/file-conventions/page
---

嵌套字段

字段必需？描述
title可选卡片列表的标题。默认为 下一步。
description可选卡片列表的描述。
链接必需指向其他文档页面的链接列表。每个列表项都应该是相对 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 文档中，概念性页面位于 Building Your Application 部分。
  • 参考性 页面用于解释特定的 API。 它们通常更短，更集中。 在 Next.js 文档中，参考性页面位于 API Reference 部分。

须知: 根据您要贡献的页面，您可能需要遵循不同的声音和风格。 例如，概念性页面更具指导性，并使用您来称呼用户。 参考页面更具技术性，它们使用更多祈使语气词，如“创建、更新、接受”，并且倾向于省略您这个词。

语气

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

  • 撰写清晰、简洁的句子。避免离题。
    • 如果您发现自己使用了很多逗号，请考虑将句子分成多个句子或使用列表。
    • 将复杂词汇替换为更简单的词汇。例如，使用 “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> 标签在页面之间创建链接”。
  • 以第二人称（你/你的）写作。这更个性化且更具吸引力。
  • 使用性别中立的语言。在指代受众时，使用 “developers”、“users” 或 “readers”。
  • 如果添加代码示例，请确保它们格式正确且可运行。

虽然这些指南并非详尽无遗，但它们应该可以帮助您入门。如果您想更深入地学习技术写作，请查看 Google Technical Writing Course。

感谢您为文档做出贡献并成为 Next.js 社区的一份子！