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

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

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

┌─────────────────────────────────────────────────────────────────────────┐
│                         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()

[Clear explanation]

```javascript
// Code example demonstrating the answer
```

[Clear explanation with code if needed]

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

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

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

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

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

---

<!-- ❌ BAD: Builds up to the answer -->

**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 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           │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

undefined

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

undefined

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

---

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

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

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

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

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

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

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

---

<!-- ✓ 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.

<!-- ✓ 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.

// ✓ 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"

// 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)
})

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

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

// ❌ 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
}

// ❌ 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)

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

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

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

// 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
    })
  })
})