文档贡献指南

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

{
  "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-) 来更改项的顺序。

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

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

但是，在 路由部分 中，文件前面都加了两个数字，按照开发人员应该学习这些概念的顺序排序

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

要快速找到页面，您可以使用 ⌘ + P (Mac) 或 Ctrl + P (Windows) 打开 VSCode 中的搜索栏。然后，键入您要查找的页面的 slug。例如 defining-routes

为什么不使用清单？

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

元数据

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

必填字段

以下字段是**必填**的

---
title: Page Title
description: Page Description
---

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

可选字段

以下字段是**可选**的

---
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 路由器**和**页面路由器**中的大多数功能完全不同，因此它们的文档分别保存在不同的部分（02-app 和 03-pages）中。但是，它们之间也有一些共享的功能。

共享页面

为了避免内容重复并防止内容不同步，我们使用 source 字段将内容从一个页面提取到另一个页面。例如，<Link> 组件在**App** 和**Pages** 中的行为大多相同。与其复制内容，我们可以将内容从 app/.../link.mdx 提取到 pages/.../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.

---
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 路由器**或**页面路由器**特定的内容。例如，<Link> 组件有一个 shallow 属性，它仅在**Pages** 中可用，而在**App** 中不可用。

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

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>组件本身。

import Link from 'next/link'
 
export default function Page() {
  return <Link href="/about">About</Link>
}

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

语言和文件名

代码块应包含一个标题，其中包括语言和文件名。添加filename属性以渲染一个特殊的终端图标，帮助用户了解在何处输入命令。例如

```bash filename="Terminal"
npx create-next-app
```

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

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

TS和JS切换器

添加语言切换器以在TypeScript和JavaScript之间切换。代码块应首先为TypeScript，并提供JavaScript版本以满足用户需求。

目前，我们一个接一个地编写TS和JS示例，并使用switcher属性将它们链接起来。

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

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

行高亮

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

单行：highlight={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} />

输出

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

备注

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

> **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.

输出

注意：这是一个单行备注。

注意:

• 我们也使用此格式进行多行备注。
• 有时有多个值得了解或牢记的要点。

相关链接

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

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

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

---
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
---

嵌套字段

图表

图表是解释复杂概念的好方法。我们使用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 使用。如果你发现自己使用了是和被等词，你可能使用了被动语态。
• 避免使用简单、快速、容易、仅仅等词。这些词是主观的，可能会让用户感到沮丧。
• 避免使用不要、不能、不会等否定词。这可能会让读者感到沮丧。
  • 例如，“你可以使用Link组件在页面之间创建链接” 而不是 “不要使用<a>标签在页面之间创建链接”。
• 使用第二人称（你/你的）。这更具个人性和吸引力。
• 使用性别中立的语言。在提及受众时，使用开发者、用户或读者。
• 如果添加代码示例，请确保它们格式正确且有效。

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

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