Next.js 文档写作规范详解：Frontmatter 模式、代码块格式与 MDX 组件标准

2026-09-04 18:08:37作者：冯爽妲Honey

Next.js 官方文档（docs/ 目录，共 500+ 篇 MDX）遵循一套统一的写作规范，完整定义在仓库的 DOC-CONVENTIONS.md 中。本文基于该规范文件，结合 docs/ 下的真实文档与根目录 package.json 的校验脚本，系统讲解 Frontmatter 字段模式、代码块格式化规则、MDX 组件用法、App Router 与 Pages Router 的共享内容机制，以及文档提交前的校验流程。读完本文，你将为 Next.js 仓库贡献或维护 MDX 文档时具备一套可直接照做的完整操作标准。

规范文档的定位

DOC-CONVENTIONS.md 位于 .agents/skills/update-docs/ 目录下，是面向维护者的 "update-docs" 技能（见 SKILL.md）的参考文件。该技能的工作流是：先通过 git diff canary...HEAD --stat 分析代码变更，再通过 CODE-TO-DOCS-MAPPING.md 将源码路径映射到文档路径，最后依据 DOC-CONVENTIONS 的格式规则完成文档更新。也就是说，这套规范服务于一个真实场景——代码改了之后，让文档以统一、可校验的格式同步更新。

从源码结构看，仓库文档区分为两大块：docs/01-app/（App Router 文档，下含 01-getting-started/、02-guides/、03-api-reference/）和 docs/02-pages/（Pages Router 文档），这正是下文所有 "source 共享内容" 规则发挥作用的前提。

Frontmatter 模式（Frontmatter Schema）

所有 MDX 文件必须以 --- 分隔符包裹的 YAML frontmatter 开头。

必填字段

字段	说明	示例
`title`	页面标题，用于 SEO 和标题（2-3 个词）	`title: Image Component`
`description`	简短描述（1-2 句话）	`description: Optimize images using next/image.`

可选字段

字段	说明	示例
`nav_title`	导航侧边栏使用的更短标题	`nav_title: Image`
`source`	从另一个页面拉取内容（避免重复维护）	`source: app/api-reference/components/image`
`related`	"Next Steps" 相关链接区块	见下方格式
`version`	开发阶段指示器	`version: experimental`

related 链接格式

related 字段渲染为页面底部的 "Next Steps" 区块，标准格式如下：

---
title: My Feature
description: Description here.
related:
  title: Next Steps
  description: Learn more about related features.
  links:
    - app/api-reference/components/image
    - app/guides/optimizing/images
---

version 字段的取值

experimental —— 实验性功能，可能变化；
legacy —— 遗留功能，建议寻找替代方案；
unstable —— 不稳定 API，不建议在生产环境使用；
RC —— 发布候选版本。

在仓库中可以验证这一字段的真实用法，例如 offline-support.mdx、proxyClientMaxBodySize.mdx、staleTimes.mdx 等文档均在 frontmatter 中声明了 version: experimental。

代码块规范（Code Block Conventions）

基本语法

```language filename="path/to/file.ext"
code here


### 必须掌握的属性

| 属性 | 使用场景 | 示例 |
| ---- | ---- | ---- |
| `filename` | 代码示例必须始终标注 | `filename="app/page.tsx"` |
| `switcher` | 同时提供 TS 和 JS 版本时 | `switcher` |
| `highlight` | 高亮特定行 | `highlight={1,3-5}` |

### TypeScript / JavaScript 切换器模式

**约定：TypeScript 版本在前，JavaScript 版本在后**，两者都带 `switcher` 属性，页面上渲染为可切换的两个 Tab：

```mdx
```tsx filename="app/page.tsx" switcher
import type { Metadata } from 'next'

export const metadata: Metadata = {
  title: 'My Page',
}

export const metadata = {
  title: 'My Page',
}


### 终端命令

终端命令使用 `bash` 语言标识，且**不加** `filename` 属性：

```mdx
```bash
npm install next


### 行高亮语法

```text
highlight={1}        # 单行
highlight={1,3}      # 多行
highlight={1-5}      # 行范围
highlight={1,3-5,8}  # 组合写法

一个真实示例见 image.mdx，其开头的最小可用示例就遵循了上述规范：

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/profile.png"
      width={500}
      height={500}
      alt="Picture of the author"
    />
  )
}

MDX 组件

AppOnly / PagesOnly：按路由隔离内容

在 App Router 与 Pages Router 共享的文档中，用这两个组件包裹路由专属内容：

<AppOnly>

This content only appears in App Router documentation.

</AppOnly>

<PagesOnly>

This content only appears in Pages Router documentation.

</PagesOnly>

重要细节：组件内部必须保留空行，否则 markdown 解析会出错。仓库中 image.mdx 就是一个范例——它用 <PagesOnly> 包裹了一段仅面向 Pages Router 用户的迁移提示，且严格遵守了空行规则。docs/01-app/ 下有大量指南（如 02-guides/ 中的 authentication、incremental-static-regeneration 等）都使用了这一对组件。

Image 组件：明暗主题双图

需要同时提供亮色/暗色变体的图片时：

<Image
  alt="Description of the image"
  srcLight="/docs/light/image-name.png"
  srcDark="/docs/dark/image-name.png"
  width={1600}
  height={800}
/>

提示框（Notes / Callouts）

单行提示：

> **Good to know**: Important information here.

多行提示：

> **Good to know**:
>
> - First point
> - Second point
> - Third point

Props 表格

Props 表格需要用 HTML <div> 包裹，使移动端可以横向滚动：

<div style={{ overflowX: 'auto', width: '100%' }}>

| Prop              | Example             | Type    | Status   |
| ----------------- | ------------------- | ------- | -------- |
| [`src`](#src)     | `src="/image.png"`  | String  | Required |
| [`alt`](#alt)     | `alt="Description"` | String  | Required |
| [`width`](#width) | `width={500}`       | Integer | -        |

</div>

Status 列的取值约定：

Required —— 必须提供；
- —— 可选；
Deprecated —— 将被移除，请使用替代项。

image.mdx 的 Props 表格即完全按此格式书写：src、alt 标记为 Required，onLoadingComplete 标记为 Deprecated，每个 prop 名称都是指向正文 #### 小节的锚点链接（如 src），形成"表格索引 + 详情小节"的双层结构。

共享内容模式（Shared Content Pattern）

这是 Next.js 文档体系的核心机制：App Router 文档是唯一内容源（source of truth），Pages Router 文档通过 frontmatter 的 source 字段直接复用，避免同一份 API 文档维护两份。

规范中给出的示例配对：

App Router（内容源）：docs/01-app/03-api-reference/02-components/image.mdx —— 包含完整文档，并用 <AppOnly> / <PagesOnly> 处理路由差异段落；
Pages Router（消费方）：docs/02-pages/03-api-reference/01-components/image.mdx：

---
title: Image Component
description: Optimize images using next/image.
source: app/api-reference/components/image
---

source 字段会让 Pages Router 页面直接拉取 App Router 文档的内容。在仓库中可以验证该模式的规模：docs/02-pages/ 下有 111 个 MDX 文件以 source: app/... 开头声明复用关系，例如 docs/02-pages/01-getting-started/01-installation.mdx 声明 source: app/getting-started/installation，对应内容源是 docs/01-app/01-getting-started/01-installation.mdx。

对贡献者的直接含义（来自 SKILL.md 的工作流）：如果你要更新某段内容，先检查目标文档是否带有 source 字段——如果是，就编辑 App Router 一侧的内容源，而不是 Pages Router 的"空壳"文件；同时用 source: app/api-reference 之类的模式在 docs/02-pages/ 中检索是否存在消费方，确保两端一致。

写作风格（Writing Style）

语气（Voice）

指南（Guides）：教学口吻，用 "you" 称呼读者；
API 参考（API Reference）：技术口吻，使用祈使动词（"create"、"pass"、"return"）。

清晰性（Clarity）

用通俗词代替复杂词；
表述要具体：说 "the src prop"，而不是 "this prop"；
除非同时解释，否则避免行话。

页面结构（Structure）

规范的典型页面由五段构成：

简短引言（是什么、为什么）；
最小可用示例（minimal working example）;
详细参考 / 选项说明；
面向不同使用场景的示例；
相关链接（通过 frontmatter 的 related 字段）。

文件命名规范

使用 kebab-case：generate-metadata.mdx；
需要排序时加数字前缀：01-installation.mdx；
目录索引页：index.mdx。

仓库中的实际结构印证了这三条规则，例如 docs/01-app/01-getting-started/ 下的 01-installation.mdx、02-project-structure.mdx、11-css.mdx 均带数字前缀，而 docs/01-app/index.mdx、docs/01-app/03-api-reference/index.mdx 承担目录索引职责。

校验命令

提交文档前运行：

pnpm lint              # 完整 lint 检查
pnpm prettier-fix      # 自动修复格式
pnpm types             # TypeScript 检查

这三个命令在根目录 package.json 中的实际定义值得展开：

lint 并非单一 eslint 检查，而是 run-p test-types lint-typescript prettier-check "lint-eslint ." lint-ast-grep lint-language check-unused-turbo-tasks 的并行组合，覆盖类型、格式、ESLint、AST 规则和语言风格；
prettier-fix 即 prettier --write .，会对全仓库文件做格式化写入；
types 即 lerna run types --stream，在各工作区包内流式执行 TypeScript 检查。

因此文档 PR 的完整校验链路是：格式问题交给 pnpm prettier-fix 自动修复，结构性/类型问题用 pnpm lint 和 pnpm types 把关。