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:

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

---
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 for key terms]

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

---

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

Explanation of the first step Explanation of the second step Detailed explanation with code examples Detailed explanation with code examples **Quick Rule of Thumb:** [Memorable summary or mnemonic]

---

[The API/Implementation Section]

[How to actually use the concept in code]

Basic Usage

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

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

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

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

**The Trap:** [Clear explanation of what goes wrong and why]

---

[Advanced Patterns Section]

[Real-world patterns and best practices]

Pattern Name

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

// Usage
const result = await realWorldExample()

---

Key Takeaways

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

---

Test Your Knowledge

**Answer:**

[Clear explanation]

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

**Answer:**

[Clear explanation with code if needed]

[Aim for 5-6 questions covering the main topics]

---

Related Concepts

How it connects to this concept How it connects to this concept

---

Reference

Official MDN documentation for the main concept Additional MDN reference

Articles

Brief description of what the reader will learn from this article. [Aim for 4-6 high-quality articles]

Videos

Brief description of what the video covers. [Aim for 3-4 quality videos] ```

---

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

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

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

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

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

## == 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):

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

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:

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

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

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

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

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

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

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

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

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

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

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