文档
社区
贡献指南

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

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

为什么贡献?

开源工作永无止境，文档工作也是如此。向文档投稿是初学者参与开源的好方法，也是经验丰富的开发者在与社区分享知识的同时阐明较复杂问题的好途径。

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

如何贡献

文档内容可以在 Next.js repo (opens in a new tab) 中找到。 要进行贡献，你可以直接在 GitHub 上编辑文件，或者克隆存储库并在本地编辑文件。

GitHub Workflow

如果你是 GitHub 的新手，我们建议你阅读 GitHub Open Source Guide (opens in a new tab) 学习如何 fork 仓库, 创建分支, 和提交 pull request.

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

编写 MDX

文档是用 MDX (opens in a new tab) 编写的, MDX 是一种支持 JSX 语法的 markdown 格式。允许我们在文档中嵌入 React 组件。 请参阅 GitHub Markdown Guide (opens in a new tab) 快速了解 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 用户使用以下插件：

Review 流程

一旦你提交了你的贡献，Next.js 或 Developer Experience 团队将 review 你的更改，提供反馈，并在准备好后合并 pull request。

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

提示: 在提交 PR 之前，执行 pnpm prettier-fix 运行 Prettier

文件结构

文档使用文件系统路由。 /docs (opens in a new tab) 内的每个文件夹和文件代表一个路由段。这些段用于生成 URL 路径、导航和面包屑。

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

例如，在 functions API 参考 中，页面按字母顺序排序，因为这样开发人员可以更容易地找到特定的函数：

03-functions
├── cookies.mdx
├── draft-mode.mdx
├── fetch.mdx
└── ...

但是，在 routing 章节，文件前缀为两位数的数字，按照开发人员应该学习这些概念的顺序排序：

02-routing
├── 01-defining-routes.mdx
├── 02-pages-and-layouts.mdx
├── 03-linking-and-navigating.mdx
└── ...

要快速查找页面，你可以使用 ⌘ + P (Mac) 或 Ctrl + P (Windows)打开 VSCode 上的搜索栏。然后输入要查找的页面的标题。例如 defining-routes

为什么不用 manifest?

我们考虑过使用 manifest 文件（另一种流行的生成文档导航的方法），但我们发现 manifest 文件会很快与文件不同步。文件系统路由迫使我们考虑文档的结构，而且感觉更适合 Next.js

元数据

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

必填字段

以下字段为必填:

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

最好将页面标题限制在 2-3 个词语（例如：优化图像）和描述为 1-2 个句子（例如了解如何在 Next.js 中优化图像）

可选字段

以下字段为可选:

FieldDescription
nav_title覆盖导航中的页面标题。当页面标题太长而无法容纳时，这很有用。如果未提供，则使用 title 字段。
source将内容拉入共享页面。请看共享页面。
related文档底部的相关页面列表。它们会自动变成卡片。请看 相关链接。
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
---

App 和 Pages 文档

由于 App Router 和 Pages Router 的大部分功能完全不同，因此它们的文档被分别放在不同的部分(02-app 和 03-pages)。不过，它们之间也有一些共享的特性。

共享页面

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

app/.../link.mdx
---
title: <Link>
description: <Link> 组件的 API 参考
---
 
本 API 参考将帮助您了解如何使用 Link 组件的道具和 Link 组件可用的配置选项。
pages/.../link.mdx
---
title: <Link>
description: <Link> 组件的 API 参考
source: app/api-reference/components/link
---
 
{/* 不要编辑此页 */}
{/* 本页内容从 source 拉取 */}

因此，我们可以在一个地方编辑内容，并在两个版块中反映出来。

共享内容

在共享页面中，有时可能会有 App Router 或 Pages Router 特定的内容。例如， <Link> 组件有一个shallow 属性，只有在 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 编写的。不过，您也可以使用任何支持的语言, 以下是完整的语言列表 full list (opens in a new tab).

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

Language后缀名
包含 JSX 的 JavaScript 文件```jsx.js
不含 JSX 的 JavaScript 文件```js.js
包含 JSX 的 TypeScript 文件```tsx.tsx
不含 JSX 的 TypeScript 文件```ts.ts

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 (opens in a new tab)。

行高亮

代码行可以高亮显示。当你想让别人注意到代码的某个特定部分时，这很有用。您可以通过向 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} />

Output:

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

注释

对于重要但不关键的信息，可使用注释。注释是添加信息的好方法，不会分散用户对主要内容的注意力。

notes.mdx
> **小贴士**: 这是一个单行注释。
 
> **小贴士**:
>
> - 我们也会使用这种格式进行多行注释。
> - 有时候会有多个值得注意或谨记的要点。

Output:

小贴士: 这是一个单行注释。

小贴士:

  • 我们也会使用这种格式进行多行注释。
  • 有时候会有多个值得注意或谨记的要点。

相关链接

相关链接通过提供合适的下一步链接来指导用户的学习过程。

  • 链接将以卡片形式显示在页面主内容之下。

  • 有子页面的页面会自动生成链接。例如，优化 章节就有指向其所有子页面的链接.

使用页面元数据中的 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可选卡片列表的描述。
links必选指向其他文档页面的链接列表。每个列表项都应是一个相对 URL 路径(不含最前面的斜线)，例如 app/api-reference/file-conventions/page

图表

图表是解释复杂概念的好方法。我们按照 Vercel 的设计指南使用 Figma (opens in a new tab) 创建图表。

这些图表目前保存在我们私有 Next.js 站点的 /public 文件夹中。如果您想更新或添加图表，请创建 GitHub issue (opens in a new tab)。

自定义组件和 HTML

这些是文档中可用的 React 组件: <Image /> (next/image)， <PagesOnly />，<AppOnly />，<Cross /> 和 <Check />。 我们不允许在文档中使用 <details>

如果您有关于新组件的想法，请创建 GitHub issue (opens in a new tab).

风格指南

本节包含针对技术写作新手的文档写作指南。

页面模板

虽然我们没有严格的页面模板，但你会在文档中看到重复出现的页面部分：

  • 概述: 页面的第一段应告诉用户该功能是什么，有什么用途。然后是一个最基本的用例或 API 参考
  • 约定: 如果功能有约定，则应在此处加以说明.
  • 示例: 展示如何在不同的用例中使用该功能。
  • API 表: API 页面应在页面顶部有一个概览表，并尽可能提供跳转到各节的链接。
  • 下一步 (相关链接): 添加相关页面链接，引导用户学习。

根据需要添加这些部分。

页面类型

文档页面也分为两类： 概念性和参考性

  • 概念性 页面用于解释概念或特性。它们通常比参考页更长，包含更多的信息。在 Next.js 文档中，概念性页面位于 构建应用程序 章节。
  • 参考性 页面用于解释特定的 API。 它们通常更简短，更聚焦。在 Next.js 文档中，参考性页面位于 API 参考 章节。

小贴士: 你可能需要使用不同的语言和风格。例如，概念性页面更具指导性，使用 "你 "来称呼用户。而参考性页面则更具技术性，使用 "创建、更新、接受" 等命令式词语，并倾向于省略 "你" 这个词。

语气

以下是维持文档语气和风格一致的几点指导原则:

  • 使用简明的语句，避免散乱的内容。
    • 如果你发现自己使用了很多逗号，考虑将其分解为多个句子，或使用列表。
    • 使用简单的词汇代替复杂的词汇。例如,使用 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 等否定词汇，这也可能会让用户感到气馁。
    • 例如，"You can use the Link component to create links between pages"，而不是 "Don't use the <a> tag to create links between pages" 。
  • 使用第二人称( you / your )。这样更个性化，也更有吸引力。
  • 使用性别中立的语言。提到受众时使用 developers，users 或 readers 。
  • 如果添加代码示例，请确保其格式正确且可运行。

尽管这些指导原则并不详尽，但它们应该可以帮助你开始着手。如果你想更深入地了解技术写作，可以查看 Google 技术写作教程 (opens in a new tab)。

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

概览