write-concept

技能：编写 JavaScript 概念文档

在为 33 JavaScript Concepts 项目编写或改进概念文档页面时，使用此技能。

适用场景

• 在 /docs/concepts/ 中创建新的概念页面
• 重写或大幅改进现有概念页面
• 检查现有概念页面的质量和完整性
• 为概念补充说明内容

目标读者

请记住：读者可能从未编写过代码，也可能刚开始学习 JavaScript。写作时要体谅初学者，同时为中级开发者提供足够的深度。让复杂主题也显得易于理解；如果读者需要先掌握其他知识，请提供相关前置知识的链接，不要想当然地认为他们已经了解。

写作指南

语气和风格

• 轻松对话，但有权威性：像向一位聪明的朋友解释那样写
• 鼓励读者：让复杂主题也显得易于理解
• 注重实践：聚焦真实应用和使用场景
• 简洁：尊重读者的时间，避免不必要的冗长
• 以问题引导：用读者可能会问的问题开启各个部分

避免 AI 生成式语言

文字必须读起来像出自真人，而不是 AI。以下是需要避免的具体模式：

避免使用的词语和短语

❌ 避免使用	✓ 改用
“掌握 [概念]”	“学习 [概念]”
“大幅变得更简单／更好”	“简单得多”或“更简洁”
“一个根本性的事情”	“一件简单的事”
“最重要的概念之一”	“这是一个重要概念”
“关键要点”	“需要记住的要点”
“深入理解 X 可以显著改善”	“熟练掌握 X 能让 Y 更容易”
“要真正理解”	“我们来看看”或“下面介绍”
“这至关重要”	“这里容易让人困惑”
“值得注意的是”	直接陈述事实
“重要的是要记住”	“别忘了：”或“记住：”
“为了”	“要”
“由于……这一事实”	“因为”
“归根结底”	完全删去
“说到……”	删去或改写
“在本节中，我们将”	直接开始解释
“如前所述”	删去或链接到相应部分

避免重复使用强调句式

不要反复使用同一种开场句式来强调内容。可以换着使用：

不要反复使用……	可换用……
“关键见解：”	“别忘了：”、“规律是：”、“关键在于：”
“最佳实践：”	“专业提示：”、“快速检查：”、“养成一个好习惯：”
“重要：”	“注意：”、“提醒：”、“请留意：”
“记住：”	“请记住：”、“规则是：”、“可以这样理解：”

避免过度使用破折号（—）

AI 生成的文本经常过度使用破折号。请减少使用，优先选择句号、逗号或冒号：

❌ 过度使用破折号	✓ 更好的替代方式
“async/await — 这是一种语法糖……”	“async/await。它是一种语法糖……”
“理解 Promises — async/await 的基础……”	“先理解 Promises。async/await 构建于其之上……”
“不会抛出错误 — 你只会得到……”	“不会抛出错误。你只会得到……”
“在 async 函数之外 — 但只在……”	“在 async 函数之外，但只在……”
“快速失败 — 如果任何 Promise 被拒绝……”	“会快速失败。如果任何 Promise 被拒绝……”
“实现相同的效果 — 选择……”	“实现相同的效果。选择……”

可以使用破折号的情况：

• 在 Key Takeaways 部分（编号列表的格式统一时）
• 在 MDN 卡片标题中（例如：“async function — MDN”）
• 在面试回答的分步说明中（结构化格式）
• 少量使用，适用于自然的插入语

**经验法则：**在一篇 1500 词的文档中，除结构化部分外，破折号超过 10 到 15 个就算过度使用。写完后，搜索“—”并逐一评估。

最高级词语和填充词

避免使用不传达任何信息的模糊最高级词语：

❌ 避免使用	✓ 替换为
"dramatically"	"much"，或直接删掉
"fundamentally"	"simply"，或具体说明什么是根本性的
"incredibly"	删掉，或具体说明
"extremely"	删掉，或具体说明
"absolutely"	删掉
"basically"	删掉（如果需要用它，说明你没有解释清楚）
"essentially"	删掉，或直接解释
"very"	删掉，或换成语气更强的词
"really"	删掉
"actually"	删掉（除非是在纠正误解）
"In fact"	删掉（直接陈述事实）
"Interestingly"	删掉（有趣与否，留给读者判断）

生硬／正式的表达

用更自然的说法替换正式的学术风格表达：

❌ 生硬的表达	✓ 更自然的说法
"It should be noted that"	"Note that"，或直接陈述
"One might wonder"	"You might wonder"
"This enables developers to"	"This lets you"
"The aforementioned"	"this"，或再次说出名称
"Subsequently"	"Then" 或 "Next"
"Utilize"	"Use"
"Commence"	"Start"
"Prior to"	"Before"
"In the event that"	"If"
"A considerable amount of"	"A lot of" 或 "Many"

增添趣味（适度使用）

偶尔加入一些亲切自然的表达，让内容不那么像机器人写的，但不要过度：

// ✓ Good: One playful comment per section
// Callback hell - nested so deep you need a flashlight

// ✓ Good: Conversational aside  
// forEach and async don't play well together — it just fires and forgets:

// ✓ Good: Relatable frustration
// Finally, error handling that doesn't make you want to flip a table.

// ❌ Bad: Trying too hard
// Callback hell - it's like a Russian nesting doll had a baby with a spaghetti monster! 🍝

// ❌ Bad: Forced humor
// Let's dive into the AMAZING world of Promises! 🎉🚀

指南：

• 每个主要章节加入一两处轻松有趣的表达就足够了
• 幽默应自然地融入内容
• 正文中避免使用表情符号（评论中偶尔使用没问题）
• 不要解释笑点
• 如果某句俏皮话效果不好，就直接表达

页面结构（请严格遵循）

每个概念页面都必须严格按照以下顺序组织：

---
title: "Concept Name: [Hook] in JavaScript"
sidebarTitle: "Concept Name: [Hook]"
description: "SEO-friendly description in 150-160 characters starting with action word"
---

[Opening hook - Start with engaging questions that make the reader curious]
[Example: "How does JavaScript get data from a server? How do you load user profiles, submit forms, or fetch the latest posts from an API?"]

[Immediately show a simple code example demonstrating the concept]

```javascript
// This is how you [do the thing] in JavaScript
const example = doSomething()
console.log(example)  // Expected output

[简要说明与读者将学到的内容之间的联系，并为关键术语添加 MDN 内联链接]

**本指南将介绍：** - 关键学习成果 1 - 关键学习成果 2 - 关键学习成果 3 - 关键学习成果 4（目标为 5-7 项） [可选：前置要求或重要提示——放在 Info 框之后] **前置要求：**本指南假设你已了解[相关概念](/concepts/related-concept)。如果你还不熟悉，请先阅读该指南！

---

[第一个主要章节——例如“X 是什么？”]

[核心说明，为任何新引入的术语／API 添加 MDN 内联链接]

[可选：使用 CardGroup 添加本章节的 MDN 参考链接]

---

[类比章节——例如“餐厅类比”]

[贴近生活的类比，让读者豁然开朗]

[用 ASCII 艺术图示意该概念]

┌─────────────────────────────────────────────────────────────────────────┐
│                          DIAGRAM TITLE                                   │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│    [Visual representation of the concept]                                │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

[核心概念章节]

[深入讲解，包含代码示例、表格和 Mintlify 组件]

第一步的说明 第二步的说明 详细说明和代码示例 详细说明和代码示例 **快速经验法则：**[易于记忆的总结或助记法]

---

[API／实现章节]

[说明如何在代码中实际使用此概念]

基本用法

// Basic example with step-by-step comments
// Step 1: Do this
const step1 = something()

// Step 2: Then this
const step2 = somethingElse(step1)

// Step 3: Finally
console.log(step2)  // Expected output

[高级模式]

// More complex real-world example

---

[常见错误章节——例如“Fetch 最常见的错误”]

[指出开发者最常犯的错误]

┌─────────────────────────────────────────────────────────────────────────┐
│                         VISUAL COMPARISON                                │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  WRONG WAY                           RIGHT WAY                           │
│  ─────────                           ─────────                           │
│  • Problem 1                         • Solution 1                        │
│  • Problem 2                         • Solution 2                        │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

// ❌ WRONG - Explanation of why this is wrong
const bad = wrongApproach()

// ✓ CORRECT - Explanation of the right way
const good = correctApproach()

**陷阱：**[清楚说明哪里会出错以及原因]

---

[高级模式章节]

[真实场景中的模式和最佳实践]

模式名称

// Reusable pattern with practical application
async function realWorldExample() {
  // Implementation
}

// Usage
const result = await realWorldExample()

---

关键要点

**请记住以下要点：**

1. 第一个关键点 — 简要说明

2. 第二个关键点 — 简要说明

3. 第三个关键点 — 简要说明

4. 第四个关键点 — 简要说明

5. 第五个关键点 — 简要说明

[建议提供 8-10 个关键要点，概括所有内容]

---

测试你的知识

**答案：**

[清晰的说明]

```javascript
// 展示答案的代码示例
```

**答案：**

[清晰的说明，如有需要可附上代码]

[建议提供 5-6 个问题，涵盖主要主题]

---

相关概念

说明它与此概念的关联 说明它与此概念的关联

---

参考资料

主要概念的 MDN 官方文档 补充的 MDN 参考资料

文章

简要介绍读者可以从这篇文章中学到什么。 [建议提供 4-6 篇高质量文章]

视频

简要介绍视频涵盖的内容。 [建议提供 3-4 个优质视频] ```

---

SEO Guidelines

SEO (Search Engine Optimization) is critical for this project. Each concept page should rank for the various ways developers search for that concept. Our goal is to appear in search results for queries like:

• "what is [concept] in JavaScript"
• "how does [concept] work in JavaScript"
• "[concept] JavaScript explained"
• "[concept] JavaScript tutorial"
• "JavaScript [concept] example"

Every writing decision — from title to structure to word choice — should consider search intent.

---

Target Keywords for Each Concept

Each concept page targets a keyword cluster — the family of related search queries. Before writing, identify these for your concept:

Keyword Type	Pattern	Example (DOM)
Primary	[concept] + JavaScript	"DOM JavaScript", "JavaScript DOM"
What is	what is [concept] in JavaScript	"what is the DOM in JavaScript"
How does	how does [concept] work	"how does the DOM work in JavaScript"
How to	how to [action] with [concept]	"how to manipulate the DOM"
Tutorial	[concept] tutorial/guide/explained	"DOM tutorial JavaScript"
Comparison	[concept] vs [related]	"DOM vs virtual DOM"

More Keyword Cluster Examples:

| Type | Keywords | |------|----------| | Primary | "JavaScript closures", "closures in JavaScript" | | What is | "what is a closure in JavaScript", "what are closures" | | How does | "how do closures work in JavaScript", "how closures work" | | Why use | "why use closures JavaScript", "closure use cases" | | Example | "JavaScript closure example", "closure examples" | | Interview | "closure interview questions JavaScript" | | Type | Keywords | |------|----------| | Primary | "JavaScript Promises", "Promises in JavaScript" | | What is | "what is a Promise in JavaScript", "what are Promises" | | How does | "how do Promises work", "how Promises work JavaScript" | | How to | "how to use Promises", "how to chain Promises" | | Comparison | "Promises vs callbacks", "Promises vs async await" | | Error | "Promise error handling", "Promise catch" | | Type | Keywords | |------|----------| | Primary | "JavaScript event loop", "event loop JavaScript" | | What is | "what is the event loop in JavaScript" | | How does | "how does the event loop work", "how event loop works" | | Visual | "event loop explained", "event loop visualization" | | Related | "call stack and event loop", "task queue JavaScript" | | Type | Keywords | |------|----------| | Primary | "JavaScript call stack", "call stack JavaScript" | | What is | "what is the call stack in JavaScript" | | How does | "how does the call stack work" | | Error | "call stack overflow JavaScript", "maximum call stack size exceeded" | | Visual | "call stack explained", "call stack visualization" |

---

Title Tag Optimization

The frontmatter has two title fields:

• title — The page's <title> tag (SEO, appears in search results)
• sidebarTitle — The sidebar navigation text (cleaner, no "JavaScript" since we're on a JS site)

The Two-Title Pattern:

---
title: "Closures: How Functions Remember Their Scope in JavaScript"
sidebarTitle: "Closures: How Functions Remember Their Scope"
---

• title 以 "in JavaScript" 结尾，以便在 SEO 中放置关键词
• sidebarTitle 不包含 "JavaScript"，让导航更简洁

规则：

1. 50-60 个字符是理想的 title 长度（Google 会截断更长的标题）
2. 概念名称放在前面 — 以主题开头，将 "JavaScript" 放在末尾
3. 添加吸引点 — 让读者了解或能够做到什么？
4. 具体明确 — 通用标题不利于排名

有效的标题公式：

title: "[Concept]: [What You'll Understand] in JavaScript"
sidebarTitle: "[Concept]: [What You'll Understand]"

title: "[Concept]: [Benefit or Outcome] in JavaScript"
sidebarTitle: "[Concept]: [Benefit or Outcome]"

标题示例：

❌ 不佳	✓ title（SEO）	✓ sidebarTitle（导航）
"Closures"	"Closures: How Functions Remember Their Scope in JavaScript"	"Closures: How Functions Remember Their Scope"
"DOM"	"DOM: How Browsers Represent Web Pages in JavaScript"	"DOM: How Browsers Represent Web Pages"
"Promises"	"Promises: Handling Async Operations in JavaScript"	"Promises: Handling Async Operations"
"Call Stack"	"Call Stack: How Function Execution Works in JavaScript"	"Call Stack: How Function Execution Works"
"Event Loop"	"Event Loop: How Async Code Actually Runs in JavaScript"	"Event Loop: How Async Code Actually Runs"
"Scope"	"Scope and Closures: Variable Visibility in JavaScript"	"Scope and Closures: Variable Visibility"
"this"	"this: How Context Binding Works in JavaScript"	"this: How Context Binding Works"
"Prototype"	"Prototype Chain: Understanding Inheritance in JavaScript"	"Prototype Chain: Understanding Inheritance"

字符数检查： 完成前，请确认 title 的长度：

• 少于 50 个字符：考虑添加更多描述性信息
• 50-60 个字符：长度理想
• 超过 60 个字符：会在搜索结果中被截断，请缩短

---

Meta Description 优化

description 字段会成为 meta description — 用户在搜索结果中看到的摘要。引人注目的描述能提高点击率。

规则：

1. 最多 150-160 个字符（Google 会截断更长的描述）
2. 在前半部分包含主要关键词
3. 如果空间允许，自然地包含次要关键词
4. 以行动词开头 — “Learn”“Understand”“Discover”（避免使用“Master”——听起来像 AI 生成的）
5. 承诺具体价值 — 用户会学到什么？
6. 以吸引人的内容结尾 — 给用户一个点击的理由

描述公式：

[Action word] [what the concept is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3].

描述示例：

概念	❌ 太短（点击率低）	✓ SEO 优化（150-160 个字符）
DOM	"Understanding the DOM"	"Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering."
闭包	"Functions that remember"	"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."
Promise	"Async JavaScript"	"Understand JavaScript Promises for handling asynchronous operations. Learn to create, chain, and combine Promises, handle errors properly, and write cleaner async code."
事件循环	"How async works"	"Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking."
调用栈	"Function execution"	"Learn how the JavaScript call stack tracks function execution. Understand stack frames, execution context, stack overflow errors, and how recursion affects the stack."
this	"Understanding this"	"Learn the 'this' keyword in JavaScript and how context binding works. Covers the four binding rules, arrow function behavior, and how to use call, apply, and bind."

字符数检查：

• 少于 120 个字符：你还可以提供更多价值——补充更多具体信息
• 150-160 个字符：长度最佳
• 超过 160 个字符：会被截断——精简措辞

---

关键词布局策略

关键词必须出现在具有策略性的位置 — 但始终要自然。关键词堆砌会损害排名。

优先布局位置：

优先级	位置	包含方式
🔴 关键	标题	在前半部分包含主要关键词
🔴 关键	Meta description	主要关键词 + 1-2 个次要关键词
🔴 关键	第一段	在前 100 个词内自然提及
🟠 高	H2 标题	使用包含关键词的疑问式标题
🟠 高	“你将学到什么”框	与主题相关的短语
🟡 中	H3 小标题	相关关键词和概念
🟡 中	关键要点	自然强化主要关键词
🟢 良好	Alt 文本	如果使用图片，请包含关键词

示例：DOM 页面关键词布局

---
title: "DOM: How Browsers Represent Web Pages in JavaScript"      ← 🔴 Primary: "in JavaScript" at end
sidebarTitle: "DOM: How Browsers Represent Web Pages"             ← Sidebar: no "JavaScript"
description: "Learn how the DOM works in JavaScript. Understand   ← 🔴 Primary: "DOM works in JavaScript"
how browsers represent HTML as a tree, select and manipulate      ← 🔴 Secondary: "manipulate elements"
elements, traverse nodes, and optimize rendering."
---

How does JavaScript change what you see on a webpage?             ← Hook question
The **Document Object Model (DOM)** is a programming interface    ← 🔴 Primary keyword in first paragraph
for web documents. It represents your HTML as a **tree of 
objects** that JavaScript can read and manipulate.

<Info>
**What you'll learn in this guide:**                              ← 🟠 Topic reinforcement
- What the DOM actually is
- How to select elements (getElementById vs querySelector)        ← Secondary keywords
- How to traverse the DOM tree
- How to create, modify, and remove elements                      ← "DOM" implicit
- How browsers render the DOM (Critical Rendering Path)
</Info>

## What is the DOM in JavaScript?                                 ← 🟠 H2 with question keyword

The DOM (Document Object Model) is...                             ← Natural repetition

## How the DOM Works                                              ← 🟠 H2 with "how" keyword

## DOM Manipulation Methods                                       ← 🟡 H3 with related keyword

## Key Takeaways                                                  ← 🟡 Reinforce in summary

关键词堆砌的警示信号：

• 同一个完整短语在每 1000 个词中出现超过 3-4 次
• 因为强行加入关键词，句子读起来不自然
• 在使用代词（“it”“they”“this”）更自然的地方使用关键词

---

回答搜索意图

Google 会为直接回答用户查询的页面排名。组织内容时，应立即满足搜索意图。

首段规则：

任何 H2 后的第一段都应直接回答其中隐含的问题。不要层层铺垫才给出答案——开门见山。

## What is the Event Loop?

Before we can understand the event loop, we need to talk about JavaScript's 
single-threaded nature. You see, JavaScript can only do one thing at a time, 
and this creates some interesting challenges. The way JavaScript handles 
this is through something called... the event loop.


## What is the Event Loop?

The **event loop** is JavaScript's mechanism for executing code, handling events, 
and managing asynchronous operations. It continuously monitors the call stack 
and task queue, moving queued callbacks to the stack when it's empty — this is 
how JavaScript handles async code despite being single-threaded.

疑问式 H2 标题：

使用符合人们搜索习惯的 H2 标题：

搜索查询	使用的 H2
“what is the DOM”	## What is the DOM?
“how closures work”	## How Do Closures Work?
“why use promises”	## Why Use Promises?
“when to use async await”	## When Should You Use async/await?

---

精选摘要优化

精选摘要显示在排名第零位，位于所有自然搜索结果之上。请通过合理组织内容来争取入选。

摘要类型及获胜方法：

┌─────────────────────────────────────────────────────────────────────────┐
│                      FEATURED SNIPPET TYPES                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  QUERY TYPE           SNIPPET FORMAT        YOUR CONTENT STRUCTURE       │
│  ───────────          ──────────────        ─────────────────────────    │
│                                                                          │
│  "What is X"          Paragraph             40-60 word definition        │
│                                             immediately after H2         │
│                                                                          │
│  "How to X"           Numbered list         <Steps> component or         │
│                                             numbered Markdown list       │
│                                                                          │
│  "X vs Y"             Table                 Comparison table with        │
│                                             clear column headers         │
│                                                                          │
│  "Types of X"         Bulleted list         Bullet list under            │
│                                             descriptive H2               │
│                                                                          │
│  "[X] examples"       Bulleted list or      Code examples with           │
│                       code block            brief explanations           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

模式 1：定义型摘要（40-60 个词）

适用于“什么是[概念]”这类查询：

## What is a Closure in JavaScript?

A **closure** is a function that retains access to variables from its outer 
(enclosing) scope, even after that outer function has finished executing. 
Closures are created every time a function is created in JavaScript, allowing 
inner functions to "remember" and access their lexical environment.

这样做效果好的原因：

• H2 与搜索查询完全匹配
• 首句中的关键词加粗
• 以 40-60 个词给出完整定义
• 解释“为什么”，而不只是“是什么”

模式 2：列表型摘要（步骤）

适用于“如何[执行操作]”这类查询：

## How to Make a Fetch Request in JavaScript

<Steps>
  <Step title="1. Call fetch() with the URL">
    The `fetch()` function takes a URL and returns a Promise that resolves to a Response object.
  </Step>
  
  <Step title="2. Check if the response was successful">
    Always verify `response.ok` before processing — fetch doesn't throw on HTTP errors.
  </Step>
  
  <Step title="3. Parse the response body">
    Use `response.json()` for JSON data, `response.text()` for plain text.
  </Step>
  
  <Step title="4. Handle errors properly">
    Wrap everything in try/catch to handle both network and HTTP errors.
  </Step>
</Steps>

模式 3：表格型摘要（比较）

适用于“[X] 与 [Y] 对比”这类查询：

## == vs === in JavaScript

| Aspect | `==` (Loose Equality) | `===` (Strict Equality) |
|--------|----------------------|------------------------|
| Type coercion | Yes — converts types before comparing | No — types must match |
| Speed | Slower (coercion overhead) | Faster (no coercion) |
| Predictability | Can produce surprising results | Always predictable |
| Recommendation | Avoid in most cases | Use by default |

```javascript
// Examples
5 == "5"    // true (string coerced to number)
5 === "5"   // false (different types)

**Pattern 4: List Snippet (Types/Categories)**

For "types of [concept]" queries:

```mdx
## Types of Scope in JavaScript

JavaScript has three types of scope that determine where variables are accessible:

- **Global Scope** — Variables declared outside any function or block; accessible everywhere
- **Function Scope** — Variables declared inside a function with `var`; accessible only within that function
- **Block Scope** — Variables declared with `let` or `const` inside `{}`; accessible only within that block

---

SEO 内容结构

内容的组织方式会影响排名和用户体验。

倒金字塔结构：

将最重要的信息放在前面。搜索引擎和用户都更喜欢能立即解答问题的内容。

┌─────────────────────────────────────────────────────────────────────────┐
│                        THE INVERTED PYRAMID                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│                                                                          │
│            ┌─────────────────────────────────────┐                       │
│            │       ANSWER THE QUESTION           │  ← First 100 words   │
│            │       Definition + Core Concept     │    (most important)  │
│            └──────────────────┬──────────────────┘                       │
│                               │                                          │
│              ┌────────────────┴────────────────┐                         │
│              │       EXPLAIN HOW IT WORKS       │  ← Next 300 words     │
│              │       Mechanism + Visual Diagram │    (supporting info)  │
│              └────────────────┬─────────────────┘                        │
│                               │                                          │
│            ┌──────────────────┴──────────────────┐                       │
│            │         SHOW PRACTICAL EXAMPLES      │  ← Code examples    │
│            │         Code + Step-by-step          │    (proof it works) │
│            └──────────────────┬──────────────────┘                       │
│                               │                                          │
│        ┌──────────────────────┴──────────────────────┐                   │
│        │            COVER EDGE CASES                  │  ← Advanced      │
│        │            Common mistakes, gotchas          │    (depth)       │
│        └──────────────────────┬──────────────────────┘                   │
│                               │                                          │
│    ┌──────────────────────────┴──────────────────────────┐               │
│    │               ADDITIONAL RESOURCES                   │  ← External  │
│    │               Related concepts, articles, videos     │    (links)   │
│    └──────────────────────────────────────────────────────┘               │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

便于浏览的内容模式：

Google 偏好易于浏览的内容。请使用以下元素：

元素	SEO 优势	使用时机
短段落	降低跳出率	始终使用（最多 2-4 句）
项目符号列表	常会成为精选摘要	包含 3 项以上内容的列表
编号列表	有机会成为“如何操作”类摘要	按顺序排列的步骤
表格	入选摘要的潜力高	比较、参考数据
粗体文本	为爬虫突出关键词	首次提及关键术语时
标题（H2/H3）	向 Google 传递结构信息	每次切换主要主题时

内容长度指南：

长度	评估	操作
少于 1,000 个词	内容太单薄	增加深度、示例和边缘情况
1,000-1,500 个词	最低可行	适用于简单概念
1,500-2,500 个词	良好	大多数概念页面的常见长度
2,500-4,000 个词	出色	综合指南的理想长度
超过 4,000 个词	需要评估	考虑拆分为多个页面

注意： 内容长度本身并不能保证排名。每个部分都必须提供价值——不要为了凑字数而填充内容。

---

SEO 内部链接

内部链接有助于搜索引擎理解网站结构，并分配页面权重。

主题集群策略：

将概念页面视为相互连接的网络。每个概念都应链接到 3-5 个相关概念：

                              ┌─────────────────┐
                      ┌───────│    Promises     │───────┐
                      │       └────────┬────────┘       │
                      │                │                │
                      ▼                ▼                ▼
              ┌───────────┐    ┌───────────────┐    ┌─────────────┐
              │async/await│◄──►│  Event Loop   │◄──►│  Callbacks  │
              └───────────┘    └───────────────┘    └─────────────┘
                      │                │                │
                      │                ▼                │
                      │       ┌───────────────┐        │
                      └──────►│  Call Stack   │◄───────┘
                              └───────────────┘

链接位置指南：

1. 在先决条件中（警告框）：

<Warning>
**Prerequisite:** This guide assumes you understand [Promises](/concepts/promises) and the [Event Loop](/concepts/event-loop). Read those first if you're not comfortable with asynchronous JavaScript.
</Warning>

2. 在正文中（自然融入上下文）：

When the callback finishes, it's added to the task queue — which is managed by the [event loop](/concepts/event-loop).

3. 在相关概念部分中：

<CardGroup cols={2}>
  <Card title="Promises" icon="handshake" href="/concepts/promises">
    async/await is built on top of Promises
  </Card>
  <Card title="Event Loop" icon="arrows-spin" href="/concepts/event-loop">
    How JavaScript manages async operations
  </Card>
</CardGroup>

锚文本最佳实践：

❌ 不佳的锚文本	✓ 优质的锚文本	原因
“点击这里”	“事件循环指南”	描述清晰，包含关键词
“这篇文章”	“我们的 Promises 概念”	告诉 Google 页面主题
“这里”	“JavaScript 闭包”	锚文本中包含关键词
“阅读更多”	“理解调用栈”	自然且信息明确

---

URL 和 Slug 最佳实践

URL（slug）是影响排名的次要因素，但仍有一定意义。

规则：

1. 使用小写 — closures 而非 Closures
2. 使用连字符 — call-stack 而非 call_stack 或 callstack
3. 保持简短 — 最多建议 3-5 个词
4. 包含主要关键词 — 概念名称
5. 避免停用词 — 除非必要，否则省略“the”“and”“in”“of”

Slug 示例：

概念	❌ 避免使用	✓ 使用
The Event Loop	the-event-loop	event-loop
this, call, apply and bind	this-call-apply-and-bind	this-call-apply-bind
Scope and Closures	scope-and-closures	scope-and-closures（可接受）或 scope-closures
DOM and Layout Trees	dom-and-layout-trees	dom 或 dom-layout-trees

注意： 本项目的 slug 已设置完毕。创建新页面时，请遵循这些规范。

---

开篇段落：SEO 的制胜之举

开篇段落是 SEO 的黄金位置。它应该：

1. 用读者正在思考的问题吸引他们
2. 自然地包含主要关键词
3. 提供简短的定义或答案
4. 引出读者将学到的内容

模板：

[Question hook that matches search intent?] [Maybe another question?]

The **[Primary Keyword]** is [brief definition that answers "what is X"]. 
[One sentence explaining why it matters or what it enables].

```javascript
// Immediately show a simple example

[简短过渡到“你将学到什么”框]

**Example (Closures):**

```mdx
Why do some functions seem to "remember" variables that should have disappeared? 
How can a callback still access variables from a function that finished running 
long ago?

The answer is **closures** — one of JavaScript's most powerful (and often 
misunderstood) features. A closure is a function that retains access to its 
outer scope's variables, even after that outer scope has finished executing.

```javascript
function createCounter() {
  let count = 0  // This variable is "enclosed" by the returned function
  return function() {
    count++
    return count
  }
}

const counter = createCounter()
console.log(counter())  // 1
console.log(counter())  // 2 — it remembers!

理解闭包可以解锁私有变量、工厂函数和模块模式等模式，这些模式为现代 JavaScript 提供了强大支持。

**Why this works for SEO:**
- Question hooks match how people search ("why do functions remember")
- Bold keyword in first paragraph
- Direct definition answers "what is a closure"
- Code example demonstrates immediately
- Natural setup for learning objectives

---

## Inline Linking Rules (Critical!)

### Always Link to MDN

Whenever you introduce a new Web API, method, object, or JavaScript concept, **link to MDN immediately**. This gives readers a path to deeper learning.

```mdx

The **[Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API)** is JavaScript's modern way to make network requests.

The **[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response)** object contains everything about the server's reply.

Most modern APIs return data in **[JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)** format.


The Fetch API is JavaScript's modern way to make network requests.

链接到相关概念页面

提及其他页面介绍的概念时，请链接到这些页面：

If you're not familiar with it, check out our [async/await concept](/concepts/async-await) first.

This guide assumes you understand [Promises](/concepts/promises).


If you're not familiar with async/await, you should learn that first.

常见的 MDN 链接格式

概念	MDN URL 格式
Web API	https://developer.mozilla.org/en-US/docs/Web/API/{APIName}
JavaScript 对象	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}
HTTP	https://developer.mozilla.org/en-US/docs/Web/HTTP
HTTP 方法	https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/{METHOD}
HTTP 标头	https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

---

代码示例最佳实践

1. 从尽可能简单的示例开始

// ✓ GOOD: Start with the absolute basics
// This is how you fetch data in JavaScript
const response = await fetch('https://api.example.com/users/1')
const user = await response.json()
console.log(user.name)  // "Alice"

2. 使用逐步讲解的注释

// Step 1: fetch() returns a Promise that resolves to a Response object
const responsePromise = fetch('https://api.example.com/users')

// Step 2: When the response arrives, we get a Response object
responsePromise.then(response => {
  console.log(response.status)      // 200
  
  // Step 3: The body is a stream, we need to parse it
  return response.json()
})
.then(data => {
  // Step 4: Now we have the actual data
  console.log(data)
})

3. 在注释中展示输出

const greeting = "Hello"
console.log(typeof greeting)  // "string"

const numbers = [1, 2, 3]
console.log(numbers.length)   // 3

4. 用 ❌ 和 ✓ 表示错误/正确模式

// ❌ WRONG - This misses HTTP errors!
try {
  const response = await fetch('/api/users/999')
  const data = await response.json()
} catch (error) {
  // Only catches NETWORK errors, not 404s!
}

// ✓ CORRECT - Check response.ok
try {
  const response = await fetch('/api/users/999')
  
  if (!response.ok) {
    throw new Error(`HTTP error! Status: ${response.status}`)
  }
  
  const data = await response.json()
} catch (error) {
  // Now catches both network AND HTTP errors
}

5. 使用有意义的变量名

// ❌ BAD
const x = [1, 2, 3]
const y = x.map(z => z * 2)

// ✓ GOOD
const numbers = [1, 2, 3]
const doubled = numbers.map(num => num * 2)

6. 从简单逐步深入到复杂

// Level 1: Basic usage
fetch('/api/users')

// Level 2: With options
fetch('/api/users', {
  method: 'POST',
  body: JSON.stringify({ name: 'Alice' })
})

// Level 3: Full real-world pattern
async function createUser(userData) {
  const response = await fetch('/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(userData)
  })
  
  if (!response.ok) {
    throw new Error(`Failed to create user: ${response.status}`)
  }
  
  return response.json()
}

---

资源筛选指南

外部资源（文章、视频）很有价值，但必须符合质量标准。

质量标准

仅收录符合以下条件的资源：

1. 专注于 JavaScript——不要收录主要介绍其他语言（C#、Python、Java 等）的资源，即使概念相似也不例外
2. 仍可访问——发布前确认所有链接均可正常使用
3. 质量高——来自可靠来源（MDN、javascript.info、freeCodeCamp、知名教育者）
4. 内容较新——避免过时资源；对于时效性较强的主题，请检查发布日期
5. 准确——浏览内容，确认其中没有教授反模式

撰写资源说明

每项资源都需要一段具体且引人入胜的两句话说明，解释其独特之处。笼统的说明会浪费读者的时间。

<Card title="JavaScript Promises Tutorial" icon="newspaper" href="...">
  Learn about Promises in JavaScript.
</Card>


<Card title="Async/Await Explained" icon="newspaper" href="...">
  A comprehensive guide to async/await.
</Card>


<Card title="JavaScript Async/Await Tutorial" icon="newspaper" href="https://javascript.info/async-await">
  The go-to reference for async/await fundamentals. Includes exercises at the end to test your understanding of rewriting promise chains.
</Card>


<Card title="JavaScript Visualized: Promises & Async/Await" icon="newspaper" href="...">
  Animated GIFs showing the call stack, microtask queue, and event loop in action. This is how async/await finally "clicked" for thousands of developers.
</Card>


<Card title="How to Escape Async/Await Hell" icon="newspaper" href="...">
  The pizza-and-drinks ordering example makes parallel vs sequential execution crystal clear. Essential reading once you know the basics.
</Card>

说明公式：

1. 第 1 句： 介绍资源的独特之处，或它具体涵盖的内容
2. 第 2 句： 说明读者为什么应该点击（能获得什么、适合哪些人、有什么突出之处）

说明中应避免：

• “……的全面指南”（含糊）
• “……的优秀教程”（含糊）
• “全面了解……”（含糊）
• “你需要了解的一切……”（陈词滥调）

推荐来源

文章（优先选择）：

来源	原因
javascript.info	内容全面、维护良好，并包含练习
MDN Web Docs	官方参考资料，始终准确
freeCodeCamp	对初学者友好，教程实用
dev.to（Lydia Hallie 等）	可视化讲解，深受社区欢迎
CSS-Tricks	DOM、浏览器 API、可视化主题

视频（优先选择）：

创作者	风格
Web Dev Simplified	清晰、适合初学者、简洁
Fireship	节奏快、现代、有趣
Traversy Media	全面的速成课程
Fun Fun Function	深入讲解，风格鲜明
Wes Bos	注重实践和真实场景

避免：

• 使用其他编程语言（C#、Python、Java）的资源，即使概念相同也不例外
• 过时的教程（现代概念却使用 ES6 之前的语法）
• 付费墙内容（除非提供免费版本）
• 低质量的 Medium 文章（检查互动情况和准确性）
• 教授反模式的资源
• 超过 2 小时的视频（如有价值，请链接到具体时间戳）

验证资源

添加任何资源之前：

1. 点击链接 — 确认链接可以打开，且不受付费墙限制
2. 浏览内容 — 确保内容准确且文笔流畅
3. 查看日期 — 对于时效性较强的主题，优先选择近期内容
4. 阅读评论和反馈 — 社区反馈有助于发现质量问题
5. 测试代码示例 — 如果包含代码，请确认代码可正常运行

---

ASCII 艺术图示

使用 ASCII 艺术图示来呈现概念。请为图示加上边框和标签：

┌─────────────────────────────────────────────────────────────────────────┐
│                        THE REQUEST-RESPONSE CYCLE                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│    YOU (Browser)                              KITCHEN (Server)           │
│    ┌──────────┐                               ┌──────────────┐           │
│    │          │  ──── "I'd like pasta" ────►  │              │           │
│    │    :)    │         (REQUEST)             │    [chef]    │           │
│    │          │                               │              │           │
│    │          │  ◄──── Here you go! ────────  │              │           │
│    │          │         (RESPONSE)            │              │           │
│    └──────────┘                               └──────────────┘           │
│                                                                          │
│    The waiter (HTTP) is the protocol that makes this exchange work!      │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

---

Mintlify 组件参考

组件	使用场景
<Info>	“你将学到什么”信息框、要点
<Warning>	常见错误、注意事项、先决条件
<Tip>	专业建议、经验法则、最佳实践
<Note>	补充背景信息、旁注
<AccordionGroup>	可展开内容、问答部分、可选的深入讲解
<Tabs>	并排比较不同方法
<Steps>	按顺序执行的流程、编号工作流
<CardGroup>	资源链接（文章、视频、参考资料）
<Card>	带图标和链接的单项资源

卡片图标参考

内容类型	图标
MDN/官方文档	book
文章/博客文章	newspaper
视频	video
课程	graduation-cap
相关概念	与上下文相关（handshake、hourglass、arrows-spin、sitemap 等）

---

质量检查清单

完成概念页面之前，请确认以下所有事项：

结构

• 开篇以吸引读者的问题引入
• 开篇之后立即展示一个简单的代码示例
• 开篇之后紧接着放置“你将学到什么”Info 信息框
• 主要章节之间用 --- 水平分隔线隔开
• 包含带有 ASCII 艺术图示的现实类比
• 包含“常见错误”或“第一大错误”章节
• 包含“要点”章节，总结 8-10 个要点
• 包含“测试你的知识”章节，附带 5-6 个问答
• 结尾按顺序包含“相关概念”、“参考资料”、“文章”、“视频”

链接

• 所有新增 Web API/方法首次出现时均附有内联 MDN 链接
• 所有相关概念均链接到其概念页面（/concepts/slug）
• 参考资料章节包含多个 MDN 链接
• 包含 4-6 篇优质文章及其简介
• 包含 3-4 个优质视频及其简介

代码示例

• 第一个代码示例非常简单
• 复杂示例包含分步注释
• 在注释中展示输出（// "result"）
• 使用 ❌ 和 ✓ 标示错误和正确模式
• 使用有意义的变量名
• 内容由简单逐步深入到复杂

内容质量

• 面向可能刚开始学习编程的人
• 使用 Warning 组件标注先决条件
• 不在缺少链接的情况下假设读者具备先前知识
• 使用表格快速查阅信息
• 使用 ASCII 图示呈现可视化概念

语言质量

• 描述以“学习”或“理解”开头（而非“精通”）
• 不要过度使用破折号（在“要点”和结构化章节之外少于 15 处）
• 不使用 AI 式最高级表述：“dramatically”、“fundamentally”、“incredibly”、“extremely”
• 不使用生硬措辞：“最重要的内容之一”、“要点”、“需要注意的是”
• 变换强调表达方式（不要总是使用“关键见解：”或“最佳实践：”）
• 谨慎加入俏皮表达（每个主要章节最多 1-2 处）
• 不使用填充词：“基本上”、“本质上”、“实际上”、“非常”、“确实”
• 句子表达直接（不要使用“为了”、“由于……的事实”）

资源质量

• 所有文章和视频链接均已验证可用
• 所有资源均聚焦 JavaScript（不包含 C#、Python、Java 资源）
• 每项资源都有具体的 2 句描述（而非泛泛而谈）
• 资源描述说明了每项资源的独特之处
• 没有过时的资源（请检查时效性主题的日期）
• 来自可靠来源的文章有 4-6 篇
• 来自优质创作者的视频有 3-4 个

---

编写测试

添加代码示例时，请在 /tests/ 中创建相应的测试：

// tests/{category}/{concept-name}/{concept-name}.test.js
import { describe, it, expect } from 'vitest'

describe('Concept Name', () => {
  describe('Basic Examples', () => {
    it('should demonstrate the core concept', () => {
      // Convert console.log examples to expect assertions
      expect(typeof "hello").toBe("string")
    })
  })
  
  describe('Common Mistakes', () => {
    it('should show the wrong behavior', () => {
      // Test the "wrong" example to prove it's actually wrong
    })
    
    it('should show the correct behavior', () => {
      // Test the "correct" example
    })
  })
})

---

SEO 检查清单

发布任何概念页面前，请检查以下要素：

标题和元描述

• 标题长度为 50-60 个字符 — 使用字符计数器检查
• 标题以 "in JavaScript" 结尾 — 将 SEO 关键词放在末尾
• 标题有吸引力 — 让读者知道他们将了解什么
• sidebarTitle 与标题一致，但不含 "in JavaScript" — 导航更简洁
• 描述长度为 150-160 个字符 — 不要浪费展示价值的空间
• 描述的第一句包含主要关键词
• 描述自然地包含 1-2 个次要关键词
• 描述以行动词开头（Learn、Understand、Discover — 避免使用 "Master"）
• 描述承诺具体价值 — 读者将学到什么？

关键词布局

• 标题中包含主要关键词
• 描述中包含主要关键词
• 第一段中包含主要关键词（前 100 个词以内）
• 至少一个 H2 标题中包含主要关键词
• 在自然适合的位置，将次要关键词放入 H2/H3 标题
• “你将学到什么”框中的条目包含关键词
• 没有关键词堆砌 — 内容读起来自然

内容结构

• 以符合搜索意图的问题式开头吸引读者
• 在前 200 个词内展示代码示例
• H2 标题后的第一段直接回答其中隐含的问题
• 内容至少有 1,500 个词（全面覆盖主题）
• 段落简短（每段最多 2-4 句）
• 使用项目符号列表列出 3 项或更多相关内容
• 使用编号列表呈现顺序流程
• 使用表格呈现比较和参考数据
• 首次提及时，将关键术语加粗并附上 MDN 链接

精选摘要优化

• “What is X” 部分包含 40-60 词的定义段落
• “How to” 部分使用编号步骤或 <Steps> 组件
• 比较部分使用表格，并配有清晰的表头
• 至少一个 H2 以问题形式表述，与搜索查询相符

内部链接

• 正文中链接到 3-5 个相关概念页面
• 使用描述性锚文本（不要使用 “click here” 或 “here”）
• 在开头的 Warning 组件中链接前置知识
• 相关概念部分包含 4 张相关概念卡片
• 链接自然地融入上下文 — 不要生硬插入

技术 SEO

• Slug 使用小写字母和连字符
• Slug 包含主要关键词
• Slug 最多为 3-5 个词
• 所有外部链接均使用有效 URL（没有失效链接）
• MDN 链接有效（检查链接能否正常打开）