docs-writer-learn

学习页面编写指南

角色设定

语气： 像一位耐心的老师，带朋友逐步理解概念 基调： 对话式、亲切、鼓励

语气与风格

如需了解语气、大小写、行话和写作模式，请调用 /docs-voice。

页面结构变体

1. 标准学习页面（最常见）

---
title: Page Title
---

<Intro>
1-3 sentences introducing the concept. Use *italics* for new terms.
</Intro>

<YouWillLearn>

* Learning outcome 1
* Learning outcome 2
* Learning outcome 3-5

</YouWillLearn>

## Section Name {/*section-id*/}

Content with Sandpack examples, Pitfalls, Notes, DeepDives...

## Another Section {/*another-section*/}

More content...

<Recap>

* Summary point 1
* Summary point 2
* Summary points 3-9

</Recap>

<Challenges>

#### Challenge title {/*challenge-id*/}

Description...

<Hint>
Optional guidance (single paragraph)
</Hint>

<Sandpack>
{/* Starting code */}
</Sandpack>

<Solution>
Explanation...

<Sandpack>
{/* Fixed code */}
</Sandpack>
</Solution>

</Challenges>

2. 章节介绍页面

适用于介绍某个章节的页面（例如 describing-the-ui.md、managing-state.md）：

<YouWillLearn isChapter={true}>

* [Sub-page title](/learn/sub-page-name) to learn...
* [Another page](/learn/another-page) to learn...

</YouWillLearn>

## Preview Section {/*section-id*/}

Preview description with mini Sandpack example

<LearnMore path="/learn/sub-page-name">

Read **[Page Title](/learn/sub-page-name)** to learn how to...

</LearnMore>

## What's next? {/*whats-next*/}

Head over to [First Page](/learn/first-page) to start reading this chapter page by page!

重要： 章节介绍页面不包含 <Recap> 或 <Challenges> 部分。

3. 教程页面

适用于分步教程（例如 tutorial-tic-tac-toe.md）：

<Intro>
Brief statement of what will be built
</Intro>

<Note>
Alternative learning path offered
</Note>

Table of contents (prose listing of major sections)

## Setup {/*setup*/}
...

## Main Content {/*main-content*/}
Progressive code building with ### subsections

No YouWillLearn, Recap, or Challenges

Ends with ordered list of "extra credit" improvements

4. 参考风格的学习页面

适用于包含大量 API 文档的页面（例如 typescript.md）：

<YouWillLearn>

* [Link to section](#section-anchor)
* [Link to another section](#another-section)

</YouWillLearn>

## Sections with ### subsections

## Further learning {/*further-learning*/}

No Recap or Challenges

标题 ID 约定

所有标题都必须使用 {/*kebab-case*/} 格式的 ID：

## Section Title {/*section-title*/}
### Subsection Title {/*subsection-title*/}
#### DeepDive Title {/*deepdive-title*/}

ID 生成规则：

• 全部使用小写
• 将空格替换为连字符
• 移除撇号和引号
• 移除或转换特殊字符（:, ?, !, ., 括号）

示例：

• "What's React?" → {/*whats-react*/}
• "Step 1: Create the context" → {/*step-1-create-the-context*/}
• "Conditional (ternary) operator (? :)" → {/*conditional-ternary-operator--*/}

教学模式

问题优先教学

先展示有问题的代码，再展示解决方案：

1. 使用 // 🔴 Avoid: 注释展示有问题的做法
2. 解释它为什么有问题（不要只说它有问题）
3. 使用 // ✅ Good: 注释展示解决方案
4. 鼓励读者尝试

渐进式增加复杂度

分层构建理解：

1. 展示最简单的可运行版本
2. 指出它的局限或重复之处
3. 逐步引入解决方案
4. 展示完整解决方案
5. 鼓励尝试：“试着更改……”

编号步骤模式

适用于多步骤流程：

作为章节标题：

### Step 1: Action to take {/*step-1-action*/}
### Step 2: Next action {/*step-2-next-action*/}

作为行内列表：

To implement this:
1. **Declare** `inputRef` with the `useRef` Hook.
2. **Pass it** as `<input ref={inputRef}>`.
3. **Read** the input DOM node from `inputRef.current`.

互动式引导

在 Sandpack 示例之后，鼓励读者尝试：

• “试着将 X 改为 Y。看看会怎样……？”
• “在上方的沙盒中试试看！”
• “分别点击每个按钮：”
• “猜猜看！”
• “验证一下……”

决策问题

帮助读者培养直觉：

“当你不确定某段代码应该放在 Effect 中还是事件处理函数中时，问问自己：这段代码为什么需要运行？”

组件放置顺序

1. <Intro> —— 放在 frontmatter 之后的第一项
2. <YouWillLearn> —— 放在 Intro 之后（标准页面和章节页面）
3. 正文内容，并在适当位置放置 <Note>、<Pitfall>、<DeepDive>
4. <Recap> —— 放在 Challenges 之前（仅标准页面）
5. <Challenges> —— 放在页面末尾（仅标准页面）

如需了解组件结构和语法，请调用 /docs-components。

代码示例

如需了解 Sandpack 文件结构、命名约定、代码风格和教学标记，请调用 /docs-sandpack。

交叉引用

何时添加链接

链接到 /learn：

• 解释概念或思维模型
• 讲解不同内容如何协同工作
• 教程和指南
• “为什么”类问题

链接到 /reference：

• API 详情、Hook 签名
• 参数列表和返回值
• 规则和限制
• “具体是什么”类问题

链接格式

[concept name](/learn/page-name)
[`useState`](/reference/react/useState)
[section link](/learn/page-name#section-id)
[MDN](https://developer.mozilla.org/...)

章节分隔线

重要： 学习页面通常不使用 --- 分隔线。标题层级已足以构建页面结构。只有在特殊情况下才考虑使用分隔线，例如将主要内容与元信息或贡献指南部分分开。

应做与不应做

应做：

• 使用“你”来称呼读者
• 先展示有问题的代码，再展示修复后的代码
• 先解释行为，再介绍概念名称
• 逐步构建概念
• 加入交互式 Sandpack 示例
• 始终如一地使用成熟的类比
• 先解释概念，再放置陷阱提示
• 使用“试试……”这样的措辞，鼓励读者动手尝试

不应做：

• 使用“简单”“容易”“只需”或时间估算
• 提及尚未介绍的概念
• 遗漏页面类型要求的组件
• 无故使用被动语态
• 在讲解概念之前放置陷阱提示
• 在章节之间使用 --- 分隔线
• 在示例中创建不必要的抽象
• 连续放置多个陷阱提示或注释，中间不加说明文字（请合并或分开）

关键规则

1. 所有标题都必须有 ID： ## Title {/*title-id*/}
2. 章节简介使用 isChapter={true} 和 <LearnMore>
3. 教程页面不使用 YouWillLearn/Recap/Challenges
4. 问题优先的讲解方式： 展示错误内容 → 解释 → 修复
5. 不得连续放置多个陷阱提示或注释： 参见 /docs-components 中的 Callout Spacing Rules

有关组件模式，请调用 /docs-components。有关 Sandpack 模式，请调用 /docs-sandpack。