Skip to main content

文档贡献指南

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

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

为什么要贡献？​

开源工作永远不会完成，文档也是如此。为文档做出贡献是初学者参与开源的好方法，也是经验丰富的开发者在与社区分享知识的同时澄清更复杂主题的好方法。

通过为 Next.js 文档做出贡献，你正在帮助我们为所有开发者构建更强大的学习资源。无论你发现了拼写错误、令人困惑的部分，还是意识到某个特定主题缺失，你的贡献都受到欢迎和赞赏。

如何贡献​

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

GitHub 工作流程​

如果你是 GitHub 新手，我们建议阅读 GitHub 开源指南 来了解如何分叉仓库、创建分支和提交拉取请求。

提示：底层文档代码位于私有代码库中，该代码库与 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 个单词（例如优化图像），将描述限制为 1-2 个句子（例如了解如何在 Next.js 中优化图像）。

可选字段​

以下字段是可选的：

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

App 和 Pages 文档​

由于App 路由和Pages 路由中的大多数功能完全不同，它们的文档分别保存在不同的部分（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 路由或Pages 路由特定的内容。例如，<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">关于</Link>
}

在提交之前，始终在本地运行示例。这将确保代码是最新的并且可以工作。

语言和文件名​

代码块应该有一个包含语言和 filename 的头部。添加 filename prop 来渲染一个特殊的终端图标，帮助用户确定在哪里输入命令。例如：

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 prop 链接它们：

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

```

```jsx filename="app/page.js" switcher

```

提示：我们计划在未来自动将 TypeScript 代码片段编译为 JavaScript。同时，你可以使用 transform.tools。

行高亮​

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

单行： highlight={1}

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

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

多行： highlight={1,3}

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

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

行范围： highlight={1-5}

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

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

图标​

以下图标可用于文档中：

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

输出：

✅ ❌

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

注释​

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

notes.mdx
> **提示**：这是单行注释。

> **提示**：
>
> - 我们也使用这种格式进行多行注释。
> - 有时有多个值得了解或记住的项目。

输出：

提示：这是单行注释。

提示：

  • 我们也使用这种格式进行多行注释。
  • 有时有多个值得了解或记住的项目。

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

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

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

example.mdx
---
related:
  description: 了解如何快速开始你的第一个应用程序。
  links:
    - /nextjs/app/building-your-application/routing/defining-routes
    - /nextjs/app/building-your-application/data-fetching
    - /nextjs/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 参考部分。

提示：根据你贡献的页面，你可能需要遵循不同的语气和风格。例如，概念性页面更具指导性，使用 你 这个词来称呼用户。参考页面更技术性，它们使用更多命令性词汇，如"创建、更新、接受"，并且倾向于省略 你 这个词。

语气​

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

  • 写清晰、简洁的句子。避免离题。
    • 如果你发现自己使用了很多逗号，考虑将句子分解为多个句子或使用列表。
    • 用更简单的词替换复杂的词。例如，用 使用 而不是 利用。
  • 注意 这个 这个词。它可能是模糊和令人困惑的，如果不清楚，不要害怕重复句子的主语。
    • 例如，Next.js 使用 React 而不是 Next.js 使用这个。
  • 使用主动语态而不是被动语态。主动句子更容易阅读。
    • 例如，Next.js 使用 React 而不是 React 被 Next.js 使用。如果你发现自己使用 was 和 by 这样的词，你可能在使用被动语态。
  • 避免使用 简单、快速、简洁、只是 等词。这是主观的，可能会让用户感到沮丧。
  • 避免使用 不要、不能、不会 等否定词。这可能会让读者感到沮丧。
    • 例如，"你可以使用 Link 组件在页面之间创建链接" 而不是 "不要使用 <a> 标签在页面之间创建链接"。
  • 用第二人称（你/你的）写作。这更个人化和吸引人。
  • 使用性别中性的语言。在提到受众时使用 开发者、用户 或 读者。
  • 如果添加代码示例，确保它们格式正确并且可以工作。

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

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

Last updated on