write-doc

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write a doc — create a new docs-site page

编写文档——创建新的文档站点页面

Author a new page in the project's documentation site. Works with any Markdown-based site (VitePress, Docusaurus, MkDocs, mdBook, Hugo).

在项目的文档站点中撰写新页面。适用于任何基于Markdown的站点（VitePress、Docusaurus、MkDocs、mdBook、Hugo）。

Before You Start

开始之前

The docs root —

docs/

docs-site/

website/

, or equivalent. Use

find . -maxdepth 3 -type f -name '*.config.*' | xargs grep -l -i 'doc'

to locate config.

The docs site's frontmatter conventions — look at 2–3 existing pages.
The site's navigation config (sidebar, navbar) — adding a file without wiring it in is invisible.

文档根目录——

docs/

、

docs-site/

、

website/

或等效目录。使用命令

find . -maxdepth 3 -type f -name '*.config.*' | xargs grep -l -i 'doc'

定位配置文件。

文档站点的前置元数据（frontmatter）规范——参考2-3个现有页面。
站点的导航配置（侧边栏、导航栏）——只添加文件而不配置导航的话，页面是不可见的。

Step 1: classify the page

步骤1：对页面进行分类

Use the Diátaxis framework (or the project's equivalent):

Type	Question it answers	Example
Tutorial	"How do I get started from zero?"	"Your first request"
Guide	"How do I solve a specific problem?"	"Migrating from v1 to v2"
Reference	"What exactly does this thing do?"	"API reference: `/v1/users` "
Concept	"What is this and why does it exist?"	"How our event system works"

Pick one. A page that tries to be two types ends up being neither.

使用Diátaxis框架（或项目的等效框架）：

类型	解答的问题	示例
教程（Tutorial）	“我如何从零开始上手？”	“你的第一个请求”
指南（Guide）	“我如何解决特定问题？”	“从v1迁移到v2”
参考文档（Reference）	“这个功能具体能做什么？”	“API参考： `/v1/users` ”
概念文档（Concept）	“这是什么，为什么会存在？”	“我们的事件系统如何运作”

选择其中一种类型。试图兼顾两种类型的页面最终会两头落空。

Step 2: find the right location

步骤2：找到合适的位置

bash

ls docs/

bash

ls docs/

Typical layout:

典型布局：

docs/

getting-started/ # tutorials

getting-started/ # 教程

guides/ # problem-driven guides

guides/ # 问题导向的指南

reference/ # API/config reference

reference/ # API/配置参考

concepts/ # explanations

concepts/ # 概念解释


Place the new file in the correct category. If the site uses locales (`index.en.md`, `index.de.md`), write the primary locale first; translations come after.


将新文件放在正确的分类目录中。如果站点使用多语言版本（如`index.en.md`、`index.de.md`），先编写主语言版本，后续再添加翻译。

Step 3: copy frontmatter from a sibling page

步骤3：复制同级页面的前置元数据

Every docs engine uses frontmatter; the exact fields vary:

yaml

---

所有文档引擎都会使用前置元数据，具体字段有所不同：

yaml

---

VitePress

title: "Page title" description: "One-line description for search + social"

title: "页面标题" description: "用于搜索和社交平台的单行描述"

Sometimes:

有时会包含：

outline: deep layout: doc

Docusaurus

id: unique-id title: Page title sidebar_position: 3

id: 唯一ID title: 页面标题 sidebar_position: 3

MkDocs — no frontmatter by default; title comes from the first H1

MkDocs — 默认无前置元数据；标题来自第一个H1


Copy frontmatter from a neighboring page and adjust.


复制相邻页面的前置元数据并按需调整。

Step 4: write with the type's shape

步骤4：按照页面类型的结构撰写内容

Tutorial

教程

State the outcome in one sentence.
List prerequisites (versions, accounts, prior knowledge).
Walk through a minimal end-to-end path.
Show the user's successful result (screenshot, output block).
Link to the next tutorial or a concept page.

用一句话说明学习成果。
列出前置条件（版本要求、账号、前置知识）。
引导完成最简端到端流程。
展示用户的成功结果（截图、输出块）。
链接到下一个教程或概念文档页面。

Guide

指南

State the problem the guide solves.
List when to use this approach vs an alternative.
Walk through the solution.
Show verification.
Link to related guides.

说明指南解决的问题。
列出何时使用此方法而非其他方案。
引导完成解决方案。
展示验证方式。
链接到相关指南。

Reference

参考文档

One-sentence summary.
Signature or config schema.
Parameters table.
Return value or output.
Example usage.
Related references.

Reference is the most mechanical. Keep examples real — tested code snippets that would run.

一句话概述。
签名或配置 schema。
参数表格。
返回值或输出结果。
使用示例。
相关参考链接。

参考文档是最偏向机械性的内容。确保示例真实可运行——使用经过测试的代码片段。

Concept

概念文档

One-sentence "what this is."
The problem it solves.
How it works, at the right level of abstraction (usually higher than reference).
Trade-offs — when it's the right tool vs when it isn't.
Links to guides and references.

一句话说明“这是什么”。
它解决的问题。
运作原理，采用合适的抽象层级（通常比参考文档更高）。
权衡取舍——何时适用、何时不适用。
链接到相关指南和参考文档。

Step 5: cross-link

步骤5：添加交叉链接

Every page cites its neighbors:

Tutorials end with "next step" links.
Guides link to relevant reference pages.
Reference entries link to the guides that use them.
Concepts link to guides that apply the concept.

Broken or dangling pages in the site are noise.

每个页面都要引用相关页面：

教程结尾添加“下一步”链接。
指南链接到相关参考文档页面。
参考文档条目链接到使用该内容的指南。
概念文档链接到应用该概念的指南。

站点中存在未关联的孤立页面会造成信息冗余。

Step 6: add to navigation

步骤6：添加到导航配置

bash

undefined

bash

undefined

VitePress sidebar

VitePress 侧边栏

cat docs/.vitepress/config.ts

Add the page path in the relevant sidebar group.

在相关侧边栏组中添加页面路径。

Docusaurus sidebars.js

Insert the doc id in the category.

在分类中插入文档ID。

MkDocs mkdocs.yml

Add under

nav:

in the right section.

在

nav:

下的对应部分添加页面。

undefined

undefined

Step 7: embed assets

步骤7：嵌入资源

Screenshots / diagrams — store adjacent to the
```
.md
```
file:
```
docs/guides/{topic}/image.png
```
. Reference with relative paths.
Code snippets — if the project has a code-snippet tester (tested-docs, dprint-runtime), use it. Otherwise copy from a file that is tested, and reference the source:
```

```
.
Videos — link, don't embed raw binary. Host on the project's tenant (not personal accounts).

截图/图表——存储在
```
.md
```
文件相邻位置：
```
docs/guides/{topic}/image.png
```
。使用相对路径引用。
代码片段——如果项目有代码片段测试工具（如tested-docs、dprint-runtime），请使用该工具。否则从经过测试的文件中复制，并标注来源：
```

```
。
视频——使用链接而非嵌入原始二进制文件。托管在项目的专属空间（而非个人账号）。

Verify

验证

bash

undefined

bash

undefined

Build the docs site to catch broken links and invalid frontmatter.

构建文档站点以检查断链和无效前置元数据。

(Project-specific command from CLAUDE.md Quick Reference.)

（参考CLAUDE.md快速参考中的项目专属命令。）

Examples:

示例：

pnpm docs:build

yarn build

mkdocs build --strict

mdbook build

The page appears in navigation — browse to it in the built site.

页面应出现在导航中——在构建后的站点中浏览确认。

undefined

undefined

Common Mistakes

常见错误

Mistake	Correction
Tutorial that jumps into the advanced use case	Tutorials assume zero context. If the reader needs to know something, state the prereq or teach it.
Reference with no examples	Add one working example per entry. Schema alone is often not enough to unblock a reader.
Guide that reads like a tutorial ("Welcome! In this guide...")	Guides are problem-first: the reader already has the problem, they're looking for the solution, not an onramp.
Writing a single page that's tutorial + reference + guide	Split. One page per type. Cross-link generously.
Page file exists but not in navigation	Users can't find it. Wire it in the sidebar/nav config (step 6).

错误	修正方式
教程直接跳入高级用例	教程假设用户毫无背景。如果读者需要了解某些知识，请明确列出前置条件或直接讲解。
参考文档没有示例	为每个条目添加一个可运行的示例。仅靠schema往往不足以帮读者解决问题。
指南写得像教程（“欢迎！在本指南中...”）	指南以问题为导向：读者已经遇到问题，他们需要的是解决方案，而非入门引导。
单个页面同时包含教程+参考+指南内容	拆分页面。一个页面对应一种类型。大量添加交叉链接。
页面文件存在但未加入导航	用户无法找到该页面。请在侧边栏/导航配置中添加（步骤6）。

write-doc

Original

Translation

Write a doc — create a new docs-site page

编写文档——创建新的文档站点页面

Before You Start

开始之前

Step 1: classify the page

步骤1：对页面进行分类

Step 2: find the right location

步骤2：找到合适的位置

Typical layout:

典型布局：

docs/

docs/

getting-started/ # tutorials

getting-started/ # 教程

guides/ # problem-driven guides

guides/ # 问题导向的指南

reference/ # API/config reference

reference/ # API/配置参考

concepts/ # explanations

concepts/ # 概念解释

Step 3: copy frontmatter from a sibling page

步骤3：复制同级页面的前置元数据

VitePress

VitePress

Sometimes:

有时会包含：

outline: deep layout: doc

outline: deep layout: doc

Docusaurus

Docusaurus

id: unique-id title: Page title sidebar_position: 3

id: 唯一ID title: 页面标题 sidebar_position: 3

MkDocs — no frontmatter by default; title comes from the first H1

MkDocs — 默认无前置元数据；标题来自第一个H1

Step 4: write with the type's shape

步骤4：按照页面类型的结构撰写内容

Tutorial

教程

Guide

指南

Reference

参考文档

Concept

概念文档

Step 5: cross-link

步骤5：添加交叉链接

Step 6: add to navigation

步骤6：添加到导航配置

VitePress sidebar

VitePress 侧边栏

Add the page path in the relevant sidebar group.

在相关侧边栏组中添加页面路径。

Docusaurus sidebars.js

Docusaurus sidebars.js

Insert the doc id in the category.

在分类中插入文档ID。

MkDocs mkdocs.yml

MkDocs mkdocs.yml

Add under nav: in the right section.

在nav:下的对应部分添加页面。

Step 7: embed assets

步骤7：嵌入资源

Verify

验证

Build the docs site to catch broken links and invalid frontmatter.

构建文档站点以检查断链和无效前置元数据。

(Project-specific command from CLAUDE.md Quick Reference.)

（参考CLAUDE.md快速参考中的项目专属命令。）

Examples:

示例：

pnpm docs:build

pnpm docs:build

yarn build

yarn build

mkdocs build --strict

mkdocs build --strict

mdbook build

Add under
`nav:`
in the right section.

在
`nav:`
下的对应部分添加页面。