@leonardomso/write-concept

---
name: write-concept
description: Write or review JavaScript concept documentation pages for the 33 JavaScript Concepts project, following strict structure and quality guidelines
---

# Skill: Write JavaScript Concept Documentation

Use this skill when writing or improving concept documentation pages for the 33 JavaScript Concepts project.

## When to Use

- Creating a new concept page in `/docs/concepts/`
- Rewriting or significantly improving an existing concept page
- Reviewing an existing concept page for quality and completeness
- Adding explanatory content to a concept

## Target Audience

Remember: **the reader might be someone who has never coded before or is just learning JavaScript**. Write with empathy for beginners while still providing depth for intermediate developers. Make complex topics feel approachable and never assume prior knowledge without linking to prerequisites.

## Writing Guidelines

### Voice and Tone

- **Conversational but authoritative**: Write like you're explaining to a smart friend
- **Encouraging**: Make complex topics feel approachable
- **Practical**: Focus on real-world applications and use cases
- **Concise**: Respect the reader's time; avoid unnecessary verbosity
- **Question-driven**: Open sections with questions the reader might have

### Avoiding AI-Generated Language

Your writing must sound human, not AI-generated. Here are specific patterns to avoid:

#### Words and Phrases to Avoid

| ❌ Avoid | ✓ Use Instead |
|----------|---------------|
| "Master [concept]" | "Learn [concept]" |
| "dramatically easier/better" | "much easier" or "cleaner" |
| "one fundamental thing" | "one simple thing" |
| "one of the most important concepts" | "This is a big one" |
| "essential points" | "key things to remember" |
| "understanding X deeply improves" | "knowing X well makes Y easier" |
| "To truly understand" | "Let's look at" or "Here's how" |
| "This is crucial" | "This trips people up" |
| "It's worth noting that" | Just state the thing directly |
| "It's important to remember" | "Don't forget:" or "Remember:" |
| "In order to" | "To" |
| "Due to the fact that" | "Because" |
| "At the end of the day" | Remove entirely |
| "When it comes to" | Remove or rephrase |
| "In this section, we will" | Just start explaining |
| "As mentioned earlier" | Remove or link to the section |

#### Repetitive Emphasis Patterns

Don't use the same lead-in pattern repeatedly. Vary your emphasis:

| Instead of repeating... | Vary with... |
|------------------------|--------------|
| "Key insight:" | "Don't forget:", "The pattern:", "Here's the thing:" |
| "Best practice:" | "Pro tip:", "Quick check:", "A good habit:" |
| "Important:" | "Watch out:", "Heads up:", "Note:" |
| "Remember:" | "Keep in mind:", "The rule:", "Think of it this way:" |

#### Em Dash (—) Overuse

AI-generated text overuses em dashes. Limit their use and prefer periods, commas, or colons:

| ❌ Em Dash Overuse | ✓ Better Alternative |
|-------------------|---------------------|
| "async/await — syntactic sugar that..." | "async/await. It's syntactic sugar that..." |
| "understand Promises — async/await is built..." | "understand Promises. async/await is built..." |
| "doesn't throw an error — you just get..." | "doesn't throw an error. You just get..." |
| "outside of async functions — but only in..." | "outside of async functions, but only in..." |
| "Fails fast — if any Promise rejects..." | "Fails fast. If any Promise rejects..." |
| "achieve the same thing — the choice..." | "achieve the same thing. The choice..." |

**When em dashes ARE acceptable:**
- In Key Takeaways section (consistent formatting for the numbered list)
- In MDN card titles (e.g., "async function — MDN")
- In interview answer step-by-step explanations (structured formatting)
- Sparingly when a true parenthetical aside reads naturally

**Rule of thumb:** If you have more than 10-15 em dashes in a 1500-word document outside of structured sections, you're overusing them. After writing, search for "—" and evaluate each one.

#### Superlatives and Filler Words

Avoid vague superlatives that add no information:

| ❌ Avoid | ✓ Use Instead |
|----------|---------------|
| "dramatically" | "much" or remove entirely |
| "fundamentally" | "simply" or be specific about what's fundamental |
| "incredibly" | remove or be specific |
| "extremely" | remove or be specific |
| "absolutely" | remove |
| "basically" | remove (if you need it, you're not explaining clearly) |
| "essentially" | remove or just explain directly |
| "very" | remove or use a stronger word |
| "really" | remove |
| "actually" | remove (unless correcting a misconception) |
| "In fact" | remove (just state the fact) |
| "Interestingly" | remove (let the reader decide if it's interesting) |

#### Stiff/Formal Phrases

Replace formal academic-style phrases with conversational alternatives:

| ❌ Stiff | ✓ Conversational |
|---------|------------------|
| "It should be noted that" | "Note that" or just state it |
| "One might wonder" | "You might wonder" |
| "This enables developers to" | "This lets you" |
| "The aforementioned" | "this" or name it again |
| "Subsequently" | "Then" or "Next" |
| "Utilize" | "Use" |
| "Commence" | "Start" |
| "Prior to" | "Before" |
| "In the event that" | "If" |
| "A considerable amount of" | "A lot of" or "Many" |

#### Playful Touches (Use Sparingly)

Add occasional human touches to make the content feel less robotic, but don't overdo it:

```javascript
// ✓ 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! 🎉🚀
```

**Guidelines:**
- One or two playful touches per major section is enough
- Humor should arise naturally from the content
- Avoid emojis in body text (they're fine in comments occasionally)
- Don't explain your jokes
- If a playful line doesn't work, just be direct instead

### Page Structure (Follow This Exactly)

Every concept page MUST follow this structure in this exact order:

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

[Brief explanation connecting to what they'll learn, with **[inline MDN links](https://developer.mozilla.org/...)** for key terms]

<Info>
**What you'll learn in this guide:**
- Key learning outcome 1
- Key learning outcome 2
- Key learning outcome 3
- Key learning outcome 4 (aim for 5-7 items)
</Info>

<Warning>
[Optional: Prerequisites or important notices - place AFTER Info box]
**Prerequisite:** This guide assumes you understand [Related Concept](/concepts/related-concept). If you're not comfortable with that yet, read that guide first!
</Warning>

---

## [First Major Section - e.g., "What is X?"]

[Core explanation with inline MDN links for any new terms/APIs introduced]

[Optional: CardGroup with MDN reference links for this section]

---

## [Analogy Section - e.g., "The Restaurant Analogy"]

[Relatable real-world analogy that makes the concept click]

[ASCII art diagram visualizing the concept]

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

---

## [Core Concepts Section]

[Deep dive with code examples, tables, and Mintlify components]

<Steps>
  <Step title="Step 1">
    Explanation of the first step
  </Step>
  <Step title="Step 2">
    Explanation of the second step
  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="Subtopic 1">
    Detailed explanation with code examples
  </Accordion>
  <Accordion title="Subtopic 2">
    Detailed explanation with code examples
  </Accordion>
</AccordionGroup>

<Tip>
**Quick Rule of Thumb:** [Memorable summary or mnemonic]
</Tip>

---

## [The API/Implementation Section]

[How to actually use the concept in code]

### Basic Usage

```javascript
// 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
```

### [Advanced Pattern]

```javascript
// More complex real-world example
```

---

## [Common Mistakes Section - e.g., "The #1 Fetch Mistake"]

[Highlight the most common mistake developers make]

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

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

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

<Warning>
**The Trap:** [Clear explanation of what goes wrong and why]
</Warning>

---

## [Advanced Patterns Section]

[Real-world patterns and best practices]

### Pattern Name

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

// Usage
const result = await realWorldExample()
```

---

## Key Takeaways

<Info>
**The key things to remember:**

1. **First key point** — Brief explanation

2. **Second key point** — Brief explanation

3. **Third key point** — Brief explanation

4. **Fourth key point** — Brief explanation

5. **Fifth key point** — Brief explanation

[Aim for 8-10 key takeaways that summarize everything]
</Info>

---

## Test Your Knowledge

<AccordionGroup>
  <Accordion title="Question 1: [Specific question about the concept]">
    **Answer:**
    
    [Clear explanation]
    
    ```javascript
    // Code example demonstrating the answer
    ```
  </Accordion>
  
  <Accordion title="Question 2: [Another question]">
    **Answer:**
    
    [Clear explanation with code if needed]
  </Accordion>
  
  [Aim for 5-6 questions covering the main topics]
</AccordionGroup>

---

## Related Concepts

<CardGroup cols={2}>
  <Card title="Related Concept 1" icon="icon-name" href="/concepts/slug">
    How it connects to this concept
  </Card>
  <Card title="Related Concept 2" icon="icon-name" href="/concepts/slug">
    How it connects to this concept
  </Card>
</CardGroup>

---

## Reference

<CardGroup cols={2}>
  <Card title="Main Topic — MDN" icon="book" href="https://developer.mozilla.org/...">
    Official MDN documentation for the main concept
  </Card>
  <Card title="Related API — MDN" icon="book" href="https://developer.mozilla.org/...">
    Additional MDN reference
  </Card>
</CardGroup>

## Articles

<CardGroup cols={2}>
  <Card title="Article Title" icon="newspaper" href="https://...">
    Brief description of what the reader will learn from this article.
  </Card>
  [Aim for 4-6 high-quality articles]
</CardGroup>

## Videos

<CardGroup cols={2}>
  <Card title="Video Title" icon="video" href="https://...">
    Brief description of what the video covers.
  </Card>
  [Aim for 3-4 quality videos]
</CardGroup>
```

---

## 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:**

<AccordionGroup>
  <Accordion title="Closures Keyword Cluster">
    | 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" |
  </Accordion>
  
  <Accordion title="Promises Keyword Cluster">
    | 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" |
  </Accordion>
  
  <Accordion title="Event Loop Keyword Cluster">
    | 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" |
  </Accordion>
  
  <Accordion title="Call Stack Keyword Cluster">
    | 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" |
  </Accordion>
</AccordionGroup>

---

### 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:**

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

- **`title`** ends with "in JavaScript" for SEO keyword placement
- **`sidebarTitle`** omits "JavaScript" for cleaner navigation

**Rules:**
1. **50-60 characters** ideal length for `title` (Google truncates longer titles)
2. **Concept name first** — lead with the topic, "JavaScript" comes at the end
3. **Add a hook** — what will the reader understand or be able to do?
4. **Be specific** — generic titles don't rank

**Title Formulas That Work:**

```
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 Examples:**

| ❌ Bad | ✓ title (SEO) | ✓ sidebarTitle (Navigation) |
|--------|---------------|----------------------------|
| `"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"` |

**Character Count Check:**
Before finalizing, verify your `title` length:
- Under 50 chars: Consider adding more descriptive context
- 50-60 chars: Perfect length
- Over 60 chars: Will be truncated in search results — shorten it

---

### Meta Description Optimization

The `description` field becomes the meta description — **the snippet users see in search results**. A compelling description increases click-through rate.

**Rules:**
1. **150-160 characters** maximum (Google truncates longer descriptions)
2. **Include primary keyword** in the first half
3. **Include secondary keywords** naturally if space allows
4. **Start with an action word** — "Learn", "Understand", "Discover" (avoid "Master" — sounds AI-generated)
5. **Promise specific value** — what will they learn?
6. **End with a hook** — give them a reason to click

**Description Formula:**

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

**Description Examples:**

| Concept | ❌ Too Short (Low CTR) | ✓ SEO-Optimized (150-160 chars) |
|---------|----------------------|--------------------------------|
| 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."` |
| Closures | `"Functions that remember"` | `"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."` |
| Promises | `"Async JavaScript"` | `"Understand JavaScript Promises for handling asynchronous operations. Learn to create, chain, and combine Promises, handle errors properly, and write cleaner async code."` |
| Event Loop | `"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."` |
| Call Stack | `"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."` |

**Character Count Check:**
- Under 120 chars: You're leaving value on the table — add more specifics
- 150-160 chars: Optimal length
- Over 160 chars: Will be truncated — edit ruthlessly

---

### Keyword Placement Strategy

Keywords must appear in strategic locations — but **always naturally**. Keyword stuffing hurts rankings.

**Priority Placement Locations:**

| Priority | Location | How to Include |
|----------|----------|----------------|
| 🔴 Critical | Title | Primary keyword in first half |
| 🔴 Critical | Meta description | Primary keyword + 1-2 secondary |
| 🔴 Critical | First paragraph | Natural mention within first 100 words |
| 🟠 High | H2 headings | Question-format headings with keywords |
| 🟠 High | "What you'll learn" box | Topic-related phrases |
| 🟡 Medium | H3 subheadings | Related keywords and concepts |
| 🟡 Medium | Key Takeaways | Reinforce main keywords naturally |
| 🟢 Good | Alt text | If using images, include keywords |

**Example: Keyword Placement for DOM Page**

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

**Warning Signs of Keyword Stuffing:**
- Same exact phrase appears more than 3-4 times per 1000 words
- Sentences read awkwardly because keywords were forced in
- Using keywords where pronouns ("it", "they", "this") would be natural

---

### Answering Search Intent

Google ranks pages that **directly answer the user's query**. Structure your content to satisfy search intent immediately.

**The First Paragraph Rule:**

The first paragraph after any H2 should directly answer the implied question. Don't build up to the answer — lead with it.

```mdx
<!-- ❌ BAD: Builds up to the answer -->
## 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.

<!-- ✓ GOOD: Answers immediately -->
## 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.
```

**Question-Format H2 Headings:**

Use H2s that match how people search:

| Search Query | H2 to Use |
|--------------|-----------|
| "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 Optimization

Featured snippets appear at **position zero** — above all organic results. Structure your content to win them.

**Snippet Types and How to Win Them:**

```
┌─────────────────────────────────────────────────────────────────────────┐
│                      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           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

**Pattern 1: Definition Snippet (40-60 words)**

For "what is [concept]" queries:

```mdx
## 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.
```

**Why this wins:**
- H2 matches search query exactly
- Bold keyword in first sentence
- 40-60 word complete definition
- Explains the "why" not just the "what"

**Pattern 2: List Snippet (Steps)**

For "how to [action]" queries:

```mdx
## 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>
```

**Pattern 3: Table Snippet (Comparison)**

For "[X] vs [Y]" queries:

```mdx
## == 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
```

---

### Content Structure for SEO

How you structure content affects both rankings and user experience.

**The Inverted Pyramid:**

Put the most important information first. Search engines and users both prefer content that answers questions immediately.

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        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)   │
│    └──────────────────────────────────────────────────────┘               │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘
```

**Scannable Content Patterns:**

Google favors content that's easy to scan. Use these elements:

| Element | SEO Benefit | When to Use |
|---------|-------------|-------------|
| Short paragraphs | Reduces bounce rate | Always (2-4 sentences max) |
| Bullet lists | Often become featured snippets | Lists of 3+ items |
| Numbered lists | "How to" snippet potential | Sequential steps |
| Tables | High snippet potential | Comparisons, reference data |
| Bold text | Highlights keywords for crawlers | First mention of key terms |
| Headings (H2/H3) | Structure signals to Google | Every major topic shift |

**Content Length Guidelines:**

| Length | Assessment | Action |
|--------|------------|--------|
| Under 1,000 words | Too thin | Add more depth, examples, edge cases |
| 1,000-1,500 words | Minimum viable | Acceptable for simple concepts |
| 1,500-2,500 words | Good | Standard for most concept pages |
| 2,500-4,000 words | Excellent | Ideal for comprehensive guides |
| Over 4,000 words | Evaluate | Consider splitting into multiple pages |

**Note:** Length alone doesn't guarantee rankings. Every section must add value — don't pad content.

---

### Internal Linking for SEO

Internal links help search engines understand your site structure and distribute page authority.

**Topic Cluster Strategy:**

Think of concept pages as an interconnected network. Every concept should link to 3-5 related concepts:

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

**Link Placement Guidelines:**

1. **In Prerequisites (Warning box):**
```mdx
<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. **In Body Content (natural context):**
```mdx
When the callback finishes, it's added to the task queue — which is managed by the [event loop](/concepts/event-loop).
```

3. **In Related Concepts Section:**
```mdx
<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>
```

**Anchor Text Best Practices:**

| ❌ Bad Anchor Text | ✓ Good Anchor Text | Why |
|-------------------|-------------------|-----|
| "click here" | "event loop guide" | Descriptive, includes keyword |
| "this article" | "our Promises concept" | Tells Google what page is about |
| "here" | "JavaScript closures" | Keywords in anchor text |
| "read more" | "understanding the call stack" | Natural, informative |

---

### URL and Slug Best Practices

URLs (slugs) are a minor but meaningful ranking factor.

**Rules:**
1. **Use lowercase** — `closures` not `Closures`
2. **Use hyphens** — `call-stack` not `call_stack` or `callstack`
3. **Keep it short** — aim for 3-5 words maximum
4. **Include primary keyword** — the concept name
5. **Avoid stop words** — skip "the", "and", "in", "of" unless necessary

**Slug Examples:**

| Concept | ❌ Avoid | ✓ Use |
|---------|---------|-------|
| 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` (acceptable) or `scope-closures` |
| DOM and Layout Trees | `dom-and-layout-trees` | `dom` or `dom-layout-trees` |

**Note:** For this project, slugs are already set. When creating new pages, follow these conventions.

---

### Opening Paragraph: The SEO Power Move

The opening paragraph is prime SEO real estate. It should:
1. Hook the reader with a question they're asking
2. Include the primary keyword naturally
3. Provide a brief definition or answer
4. Set up what they'll learn

**Template:**

```mdx
[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
```

[Brief transition to "What you'll learn" box]
```

**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!
```

Understanding closures unlocks patterns like private variables, factory functions, 
and the module pattern that power modern 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
<!-- ✓ CORRECT: Link on first mention -->
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.

<!-- ❌ WRONG: No links -->
The Fetch API is JavaScript's modern way to make network requests.
```

### Link to Related Concept Pages

When mentioning concepts covered in other pages, link to them:

```mdx
<!-- ✓ CORRECT: Internal links to related concepts -->
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).

<!-- ❌ WRONG: No internal links -->
If you're not familiar with async/await, you should learn that first.
```

### Common MDN Link Patterns

| Concept | MDN URL Pattern |
|---------|-----------------|
| Web APIs | `https://developer.mozilla.org/en-US/docs/Web/API/{APIName}` |
| JavaScript Objects | `https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}` |
| HTTP | `https://developer.mozilla.org/en-US/docs/Web/HTTP` |
| HTTP Methods | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/{METHOD}` |
| HTTP Headers | `https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers` |

---

## Code Examples Best Practices

### 1. Start with the Simplest Possible Example

```javascript
// ✓ 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. Use Step-by-Step Comments

```javascript
// 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. Show Output in Comments

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

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

### 4. Use ❌ and ✓ for Wrong/Correct Patterns

```javascript
// ❌ 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. Use Meaningful Variable Names

```javascript
// ❌ 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. Progress from Simple to Complex

```javascript
// 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()
}
```

---

## Resource Curation Guidelines

External resources (articles, videos) are valuable, but must meet quality standards.

### Quality Standards

Only include resources that are:

1. **JavaScript-focused** — No resources primarily about other languages (C#, Python, Java, etc.), even if the concepts are similar
2. **Still accessible** — Verify all links work before publishing
3. **High quality** — From reputable sources (MDN, javascript.info, freeCodeCamp, well-known educators)
4. **Up to date** — Avoid outdated resources; check publication dates for time-sensitive topics
5. **Accurate** — Skim the content to verify it doesn't teach anti-patterns

### Writing Resource Descriptions

Each resource needs a **specific, engaging 2-sentence description** explaining what makes it unique. Generic descriptions waste the reader's time.

```mdx
<!-- ❌ Generic (bad) -->
<Card title="JavaScript Promises Tutorial" icon="newspaper" href="...">
  Learn about Promises in JavaScript.
</Card>

<!-- ❌ Generic (bad) -->
<Card title="Async/Await Explained" icon="newspaper" href="...">
  A comprehensive guide to async/await.
</Card>

<!-- ✓ Specific (good) -->
<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>

<!-- ✓ Specific (good) -->
<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>

<!-- ✓ Specific (good) -->
<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>
```

**Description Formula:**
1. **Sentence 1:** What makes this resource unique OR what it specifically covers
2. **Sentence 2:** Why a reader should click (what they'll gain, who it's best for, what stands out)

**Avoid in descriptions:**
- "Comprehensive guide to..." (vague)
- "Great tutorial on..." (vague)  
- "Learn all about..." (vague)
- "Everything you need to know about..." (cliché)

### Recommended Sources

**Articles (Prioritize):**

| Source | Why |
|--------|-----|
| javascript.info | Comprehensive, well-maintained, exercises included |
| MDN Web Docs | Official reference, always accurate |
| freeCodeCamp | Beginner-friendly, practical tutorials |
| dev.to (Lydia Hallie, etc.) | Visual explanations, community favorites |
| CSS-Tricks | DOM, browser APIs, visual topics |

**Videos (Prioritize):**

| Creator | Style |
|---------|-------|
| Web Dev Simplified | Clear, beginner-friendly, concise |
| Fireship | Fast-paced, modern, entertaining |
| Traversy Media | Comprehensive crash courses |
| Fun Fun Function | Deep-dives with personality |
| Wes Bos | Practical, real-world focused |

**Avoid:**
- Resources in other programming languages (C#, Python, Java) even if concepts overlap
- Outdated tutorials (pre-ES6 syntax for modern concepts)
- Paywalled content (unless there's a free tier)
- Low-quality Medium articles (check engagement and accuracy)
- Resources that teach anti-patterns
- Videos over 2 hours (link to specific timestamps if valuable)

### Verifying Resources

Before including any resource:

1. **Click the link** — Verify it loads and isn't behind a paywall
2. **Skim the content** — Ensure it's accurate and well-written
3. **Check the date** — For time-sensitive topics, prefer recent content
4. **Read comments/reactions** — Community feedback reveals quality issues
5. **Test code examples** — If they include code, verify it works

---

## ASCII Art Diagrams

Use ASCII art to visualize concepts. Make them boxed and labeled:

```
┌─────────────────────────────────────────────────────────────────────────┐
│                        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 Components Reference

| Component | When to Use |
|-----------|-------------|
| `<Info>` | "What you'll learn" boxes, Key Takeaways |
| `<Warning>` | Common mistakes, gotchas, prerequisites |
| `<Tip>` | Pro tips, rules of thumb, best practices |
| `<Note>` | Additional context, side notes |
| `<AccordionGroup>` | Expandable content, Q&A sections, optional deep-dives |
| `<Tabs>` | Comparing different approaches side-by-side |
| `<Steps>` | Sequential processes, numbered workflows |
| `<CardGroup>` | Resource links (articles, videos, references) |
| `<Card>` | Individual resource with icon and link |

### Card Icons Reference

| Content Type | Icon |
|--------------|------|
| MDN/Official Docs | `book` |
| Articles/Blog Posts | `newspaper` |
| Videos | `video` |
| Courses | `graduation-cap` |
| Related Concepts | Context-appropriate (`handshake`, `hourglass`, `arrows-spin`, `sitemap`, etc.) |

---

## Quality Checklist

Before finalizing a concept page, verify ALL of these:

### Structure
- [ ] Opens with engaging questions that hook the reader
- [ ] Shows a simple code example immediately after the opening
- [ ] Has "What you'll learn" Info box right after the opening
- [ ] Major sections are separated by `---` horizontal rules
- [ ] Has a real-world analogy with ASCII art diagram
- [ ] Has a "Common Mistakes" or "The #1 Mistake" section
- [ ] Has a "Key Takeaways" section summarizing 8-10 points
- [ ] Has a "Test Your Knowledge" section with 5-6 Q&As
- [ ] Ends with Related Concepts, Reference, Articles, Videos in that order

### Linking
- [ ] All new Web APIs/methods have inline MDN links on first mention
- [ ] All related concepts link to their concept pages (`/concepts/slug`)
- [ ] Reference section has multiple MDN links
- [ ] 4-6 quality articles with descriptions
- [ ] 3-4 quality videos with descriptions

### Code Examples
- [ ] First code example is dead simple
- [ ] Uses step-by-step comments for complex examples
- [ ] Shows output in comments (`// "result"`)
- [ ] Uses ❌ and ✓ for wrong/correct patterns
- [ ] Uses meaningful variable names
- [ ] Progresses from simple to complex

### Content Quality
- [ ] Written for someone who might be new to coding
- [ ] Prerequisites are noted with Warning component
- [ ] No assumptions about prior knowledge without links
- [ ] Tables used for quick reference information
- [ ] ASCII diagrams for visual concepts

### Language Quality
- [ ] Description starts with "Learn" or "Understand" (not "Master")
- [ ] No overuse of em dashes (fewer than 15 outside Key Takeaways and structured sections)
- [ ] No AI superlatives: "dramatically", "fundamentally", "incredibly", "extremely"
- [ ] No stiff phrases: "one of the most important", "essential points", "It should be noted"
- [ ] Emphasis patterns vary (not all "Key insight:" or "Best practice:")
- [ ] Playful touches are sparse (1-2 per major section maximum)
- [ ] No filler words: "basically", "essentially", "actually", "very", "really"
- [ ] Sentences are direct (no "In order to", "Due to the fact that")

### Resource Quality
- [ ] All article/video links are verified working
- [ ] All resources are JavaScript-focused (no C#, Python, Java resources)
- [ ] Each resource has a specific 2-sentence description (not generic)
- [ ] Resource descriptions explain what makes each unique
- [ ] No outdated resources (check dates for time-sensitive topics)
- [ ] 4-6 articles from reputable sources
- [ ] 3-4 videos from quality creators

---

## Writing Tests

When adding code examples, create corresponding tests in `/tests/`:

```javascript
// 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 Checklist

Verify these elements before publishing any concept page:

### Title & Meta Description
- [ ] **Title is 50-60 characters** — check with character counter
- [ ] **Title ends with "in JavaScript"** — SEO keyword at end
- [ ] **Title has a compelling hook** — tells reader what they'll understand
- [ ] **sidebarTitle matches title but without "in JavaScript"** — cleaner navigation
- [ ] **Description is 150-160 characters** — don't leave value on the table
- [ ] **Description includes primary keyword** in first sentence
- [ ] **Description includes 1-2 secondary keywords** naturally
- [ ] **Description starts with action word** (Learn, Understand, Discover — avoid "Master")
- [ ] **Description promises specific value** — what will they learn?

### Keyword Placement
- [ ] **Primary keyword in title**
- [ ] **Primary keyword in description**
- [ ] **Primary keyword in first paragraph** (within first 100 words)
- [ ] **Primary keyword in at least one H2 heading**
- [ ] **Secondary keywords in H2/H3 headings** where natural
- [ ] **Keywords in "What you'll learn" box items**
- [ ] **No keyword stuffing** — content reads naturally

### Content Structure
- [ ] **Opens with question hook** matching search intent
- [ ] **Shows code example in first 200 words**
- [ ] **First paragraph after H2s directly answers** the implied question
- [ ] **Content is 1,500+ words** (comprehensive coverage)
- [ ] **Short paragraphs** (2-4 sentences maximum)
- [ ] **Uses bullet lists** for 3+ related items
- [ ] **Uses numbered lists** for sequential processes
- [ ] **Uses tables** for comparisons and reference data
- [ ] **Key terms bolded** on first mention with MDN links

### Featured Snippet Optimization
- [ ] **"What is X" section has 40-60 word definition paragraph**
- [ ] **"How to" sections use numbered steps or `<Steps>` component**
- [ ] **Comparison sections use tables** with clear headers
- [ ] **At least one H2 is phrased as a question** matching search query

### Internal Linking
- [ ] **Links to 3-5 related concept pages** in body content
- [ ] **Uses descriptive anchor text** (not "click here" or "here")
- [ ] **Prerequisites linked in Warning component** at start
- [ ] **Related Concepts section has 4 cards** with relevant concepts
- [ ] **Links appear in natural context** — not forced

### Technical SEO
- [ ] **Slug is lowercase with hyphens**
- [ ] **Slug contains primary keyword**
- [ ] **Slug is 3-5 words maximum**
- [ ] **All external links use proper URLs** (no broken links)
- [ ] **MDN links are current** (check they resolve)