docs-writer-learn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Learn Page Writer

Learn页面编写指南

Persona

角色设定

Voice: Patient teacher guiding a friend through concepts Tone: Conversational, warm, encouraging

语气风格： 像耐心的老师引导朋友理解概念 语调： 口语化、亲切、鼓励性的

Voice & Style

语气与风格

For tone, capitalization, jargon, and prose patterns, invoke

/docs-voice

关于语调、大小写、专业术语和行文风格，请参考

/docs-voice

。

Page Structure Variants

页面结构变体

1. Standard Learn Page (Most Common)

1. 标准Learn页面（最常用）

mdx

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

mdx

---
title: Page Title
---

<Intro>
1-3句话介绍核心概念。新术语使用*斜体*标注。
</Intro>

<YouWillLearn>

* 学习成果1
* 学习成果2
* 学习成果3-5

</YouWillLearn>

Section Name {/section-id/}

章节名称 {/section-id/}

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

包含Sandpack示例、注意事项、提示、深度解析等内容...

Another Section {/another-section/}

另一章节 {/another-section/}

Challenge title {/challenge-id/}

挑战标题 {/challenge-id/}

Description...

<Hint> Optional guidance (single paragraph) </Hint> <Sandpack> {/* Starting code */} </Sandpack> <Solution> Explanation... <Sandpack> {/* Fixed code */} </Sandpack> </Solution> </Challenges> ```

描述...

<Hint> 可选指导内容（单段落） </Hint> <Sandpack> {/* 初始代码 */} </Sandpack> <Solution> 解释说明... <Sandpack> {/* 修正后的代码 */} </Sandpack> </Solution> </Challenges> ```

2. Chapter Introduction Page

2. 章节介绍页面

For pages that introduce a chapter (like describing-the-ui.md, managing-state.md):

mdx

<YouWillLearn isChapter={true}>

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

</YouWillLearn>

适用于介绍整章内容的页面（如describing-the-ui.md、managing-state.md）：

mdx

<YouWillLearn isChapter={true}>

* [子页面标题](/learn/sub-page-name) - 学习...
* [另一页面](/learn/another-page) - 学习...

</YouWillLearn>

Preview Section {/section-id/}

预览章节 {/section-id/}

Preview description with mini Sandpack example

Read Page Title to learn how to...

</LearnMore>

包含迷你Sandpack示例的预览说明

阅读**页面标题** 了解如何...

</LearnMore>

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

下一步？ {/whats-next/}

Head over to First Page to start reading this chapter page by page!


**Important:** Chapter intro pages do NOT include `<Recap>` or `<Challenges>` sections.

前往第一页，逐页学习本章内容！


**重要提示：** 章节介绍页面**不包含**`<Recap>`或`<Challenges>`组件。

3. Tutorial Page

3. 教程页面

For step-by-step tutorials (like tutorial-tic-tac-toe.md):

mdx

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

<Note>
Alternative learning path offered
</Note>

Table of contents (prose listing of major sections)

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

mdx

<Intro>
简要说明将完成的项目内容
</Intro>

<Note>
提供可选的学习路径
</Note>

目录（列出主要章节的文字说明）

Setup {/setup/}

准备工作 {/setup/}

...

Main Content {/main-content/}

主要内容 {/main-content/}

Progressive code building with ### subsections

No YouWillLearn, Recap, or Challenges

Ends with ordered list of "extra credit" improvements

undefined

逐步构建代码的内容，包含### 子章节

不包含YouWillLearn、Recap或Challenges组件

结尾处列出“拓展任务”的有序列表

undefined

4. Reference-Style Learn Page

4. 参考型Learn页面

For pages with heavy API documentation (like typescript.md):

mdx

<YouWillLearn>

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

</YouWillLearn>

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

mdx

<YouWillLearn>

* [章节链接](#section-anchor)
* [另一章节链接](#another-section)

</YouWillLearn>

Sections with ### subsections

包含### 子章节的内容

Further learning {/further-learning/}

拓展学习 {/further-learning/}

No Recap or Challenges

undefined

不包含Recap或Challenges组件

undefined

Heading ID Conventions

标题ID命名规范

All headings require IDs in

{/*kebab-case*/}

format:

markdown

undefined

所有标题必须使用

{/*短横线命名法*/}

格式的ID：

markdown

undefined

Section Title {/section-title/}

章节标题 {/section-title/}

Subsection Title {/subsection-title/}

子章节标题 {/subsection-title/}

DeepDive Title {/deepdive-title/}

深度解析标题 {/deepdive-title/}


**ID Generation Rules:**
- Lowercase everything
- Replace spaces with hyphens
- Remove apostrophes, quotes
- Remove or convert special chars (`:`, `?`, `!`, `.`, parentheses)

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


**ID生成规则：**
- 全部使用小写字母
- 空格替换为短横线
- 省略撇号、引号
- 移除或转换特殊字符（`:`, `?`, `!`, `.`, 括号等）

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

Teaching Patterns

教学模式

Problem-First Teaching

问题前置教学法

Show broken/problematic code BEFORE the solution:

Present problematic approach with
```
// 🔴 Avoid:
```
comment
Explain WHY it's wrong (don't just say it is)
Show the solution with
```
// ✅ Good:
```
comment
Invite experimentation

在展示解决方案之前，先呈现有问题的代码：

展示存在问题的写法，并添加
```
// 🔴 避免：
```
注释
解释为什么这种写法错误（不要只说它不对）
展示正确写法，并添加
```
// ✅ 推荐：
```
注释
鼓励读者尝试修改

Progressive Complexity

渐进式复杂度教学

Build understanding in layers:

Show simplest working version
Identify limitation or repetition
Introduce solution incrementally
Show complete solution
Invite experimentation: "Try changing..."

分层构建理解：

展示最简可行版本
指出局限性或重复问题
逐步引入解决方案
展示完整解决方案
鼓励读者尝试：“试试把X改成Y，看看会发生什么？”

Numbered Step Patterns

分步式内容结构

For multi-step processes:

As section headings:

markdown

undefined

针对多步骤流程：

作为章节标题：

markdown

undefined

Step 1: Action to take {/step-1-action/}

步骤1：执行操作 {/step-1-action/}

Step 2: Next action {/step-2-next-action/}

步骤2：下一步操作 {/step-2-next-action/}


**As inline lists:**
```markdown
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`.


**作为内联列表：**
```markdown
实现步骤：
1. **声明** 使用`useRef` Hook创建`inputRef`。
2. **传递** 将其作为`<input ref={inputRef}>`属性。
3. **读取** 从`inputRef.current`获取输入框DOM节点。

Interactive Invitations

互动引导

After Sandpack examples, encourage experimentation:

"Try changing X to Y. See how...?"
"Try it in the sandbox above!"
"Click each button separately:"
"Have a guess!"
"Verify that..."

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

“试试把X改成Y，看看会怎样？”
“在上方的沙箱里试试吧！”
“分别点击每个按钮：”
“猜一猜！”
“验证一下...”

Decision Questions

决策引导问题

Help readers build intuition:

"When you're not sure whether some code should be in an Effect or in an event handler, ask yourself why this code needs to run."

帮助读者建立直觉：

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

Component Placement Order

组件放置顺序

```
<Intro>
```
- First after frontmatter
```
<YouWillLearn>
```
- After Intro (standard/chapter pages)
Body content with
```
<Note>
```
,
```
<Pitfall>
```
,
```
<DeepDive>
```
placed contextually
```
<Recap>
```
- Before Challenges (standard pages only)
```
<Challenges>
```
- End of page (standard pages only)

For component structure and syntax, invoke

/docs-components

```
<Intro>
```
- 位于前置元数据之后
```
<YouWillLearn>
```
- 位于Intro之后（标准/章节介绍页面适用）
正文内容，
```
<Note>
```
、
```
<Pitfall>
```
、
```
<DeepDive>
```
等组件需放置在对应上下文位置
```
<Recap>
```
- 位于Challenges之前（仅标准页面适用）
```
<Challenges>
```
- 页面末尾（仅标准页面适用）

关于组件结构与语法，请参考

/docs-components

。

Code Examples

代码示例

For Sandpack file structure, naming conventions, code style, and pedagogical markers, invoke

/docs-sandpack

关于Sandpack的文件结构、命名规范、代码风格和教学标记，请参考

/docs-sandpack

。

Cross-Referencing

交叉引用

When to Link

链接场景

Link to /learn:

Explaining concepts or mental models
Teaching how things work together
Tutorials and guides
"Why" questions

Link to /reference:

API details, Hook signatures
Parameter lists and return values
Rules and restrictions
"What exactly" questions

链接至/learn：

解释概念或思维模型
讲解各部分如何协同工作
教程与指南
解答“为什么”类问题

链接至/reference：

API细节、Hook签名
参数列表与返回值
规则与限制
解答“具体是什么”类问题

Link Formats

链接格式

markdown

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

markdown

[概念名称](/learn/page-name)
[`useState`](/reference/react/useState)
[章节链接](/learn/page-name#section-id)
[MDN](https://developer.mozilla.org/...)

Section Dividers

章节分隔线

Important: Learn pages typically do NOT use

---

dividers. The heading hierarchy provides sufficient structure. Only consider dividers in exceptional cases like separating main content from meta/contribution sections.

重要提示： Learn页面通常不使用

---

分隔线。标题层级已足够提供清晰结构。仅在特殊情况下考虑使用，比如区分主内容与元数据/贡献指南章节。

Do's and Don'ts

注意事项

Do:

Use "you" to address the reader
Show broken code before fixes
Explain behavior before naming concepts
Build concepts progressively
Include interactive Sandpack examples
Use established analogies consistently
Place Pitfalls AFTER explaining concepts
Invite experimentation with "Try..." phrases

Don't:

Use "simple", "easy", "just", or time estimates
Reference concepts not yet introduced
Skip required components for page type
Use passive voice without reason
Place Pitfalls before teaching the concept
Use
```
---
```
dividers between sections
Create unnecessary abstraction in examples
Place consecutive Pitfalls or Notes without separating prose (combine or separate)

建议做法：

使用“你”称呼读者
在展示正确代码前先展示有问题的代码
先解释行为再命名概念
逐步构建概念
包含交互式Sandpack示例
持续使用统一的类比
在讲解概念后再放置Pitfall组件
使用“试试...”这类语句鼓励读者尝试

避免做法：

使用“简单”、“容易”、“只要”或时间预估类词汇
引用尚未介绍的概念
遗漏对应页面类型所需的必填组件
无故使用被动语态
在讲解概念前放置Pitfall组件
在章节间使用
```
---
```
分隔线
在示例中创建不必要的抽象
连续放置Pitfall或Note组件而不添加分隔性文字（合并或分开）

Critical Rules

关键规则

All headings require IDs:
```
## Title {/*title-id*/}
```
Chapter intros use
isChapter={true}
and
<LearnMore>
Tutorial pages omit YouWillLearn/Recap/Challenges
Problem-first teaching: Show broken → explain → fix
No consecutive Pitfalls/Notes: See
```
/docs-components
```
Callout Spacing Rules

For component patterns, invoke

/docs-components

. For Sandpack patterns, invoke

/docs-sandpack

所有标题必须包含ID：
```
## 标题 {/*title-id*/}
```
章节介绍页面需使用
isChapter={true}
和
<LearnMore>
组件
教程页面省略YouWillLearn/Recap/Challenges组件
问题前置教学： 展示问题代码→解释原因→给出解决方案
不得连续放置Pitfall/Note组件： 参考
```
/docs-components
```
中的提示框间距规则

关于组件模式，请参考

/docs-components

。关于Sandpack模式，请参考

/docs-sandpack

。