write-concept

スキル：JavaScript の概念ドキュメントを執筆する

33 JavaScript Concepts プロジェクトの概念ドキュメントページを執筆または改善する際に、このスキルを使用します。

使用する場面

• /docs/concepts/ に新しい概念ページを作成するとき
• 既存の概念ページを書き直す、または大幅に改善するとき
• 既存の概念ページの品質と完全性をレビューするとき
• 概念の説明を追加するとき

対象読者

覚えておいてください。読者は、プログラミングが初めての人や、JavaScript を学び始めたばかりの人かもしれません。 中級開発者にも役立つ深さを保ちながら、初心者に寄り添って書きましょう。複雑なトピックも親しみやすく説明し、前提知識が必要な場合は、必ず関連する前提知識へのリンクを付けてください。

執筆ガイドライン

文体とトーン

• 会話調でありながら信頼できる：聡明な友人に説明するように書きましょう
• 励みになる：複雑なトピックも親しみやすく感じられるようにしましょう
• 実用的：実際の利用例やユースケースを中心にしましょう
• 簡潔：読者の時間を大切にし、不要に冗長な説明を避けましょう
• 問いかけを意識する：読者が抱きそうな疑問を使ってセクションを始めましょう

AI 生成文のような表現を避ける

文章は AI 生成ではなく、人間が書いたように聞こえる必要があります。避けるべきパターンを以下に示します。

避けるべき単語やフレーズ

❌ 避ける表現	✓ 代わりに使う表現
「[概念]を極める」	「[概念]を学ぶ」
「劇的に簡単／優れた」	「ずっと簡単」または「よりすっきりした」
「根本的なことが一つある」	「シンプルなことが一つあります」
「最も重要な概念の一つ」	「これは大事なポイントです」
「不可欠なポイント」	「覚えておきたい要点」
「X を深く理解すると、能力が大きく向上する」	「X をよく知っていると、Y が簡単になります」
「本当に理解するには」	「見ていきましょう」または「仕組みを説明します」
「これは非常に重要です」	「ここでつまずく人は少なくありません」
「注目すべきなのは」	そのまま要点を述べる
「忘れてはいけないのは」	「忘れないでください：」または「覚えておいてください：」
「〜するために」	「〜するには」
「〜という事実によって」	「〜だから」
「結局のところ」	完全に削除
「〜に関して言えば」	削除するか、別の表現にする
「このセクションでは、〜します」	すぐに説明を始める
「前述したように」	削除するか、該当セクションへのリンクを付ける

強調表現の繰り返しを避ける

同じ導入表現を何度も使わないようにしましょう。強調の仕方に変化をつけてください。

繰り返すのではなく...	次のように変化をつける...
「重要なポイント：」	「忘れないでください：」「このパターン：」「ここがポイントです：」
「ベストプラクティス：」	「プロのヒント：」「簡単な確認：」「よい習慣：」
「重要：」	「注意してください：」「ご注意ください：」「注：」
「覚えておいてください：」	「心に留めておいてください：」「ルール：」「こう考えてみてください：」

エムダッシュ（—）の多用

AI 生成文ではエムダッシュが多用されがちです。使用を控え、ピリオド、カンマ、コロンを優先しましょう。

❌ エムダッシュの多用	✓ よりよい代替表現
「async/await — 構文糖衣であり...」	「async/await。これは構文糖衣です...」
「Promise を理解する — async/await は...」	「Promise を理解しましょう。async/await は...」
「エラーをスローしない — ただ...」	「エラーをスローしません。ただ...」
「async 関数の外でも使える — ただし...」	「async 関数の外でも使えますが...」
「すぐに失敗する — いずれかの Promise が拒否されると...」	「すぐに失敗します。いずれかの Promise が拒否されると...」
「同じことを実現できる — 選択は...」	「同じことを実現できます。どちらを選ぶかは...」

エムダッシュを使ってもよい場合：

• Key Takeaways セクション（番号付きリストで一貫した書式を使う場合）
• MDN カードのタイトル（例：「async function — MDN」）
• 面接での回答における段階的な説明（構造化された書式）
• 括弧書きの補足として自然に読める場合に限り、控えめに使用

目安： 構造化されたセクション以外で、1500 語の文書にエムダッシュが 10～15 個以上ある場合は、多用しすぎです。執筆後に「—」を検索し、一つずつ適切かどうか確認してください。

最上級表現とフィラーワード

情報を何も追加しない曖昧な最上級表現は避けてください:

❌ 避ける	✓ 代わりに使う
「劇的に」	「かなり」または完全に削除
「根本的に」	「単純に」または何が根本的なのか具体的に述べる
「信じられないほど」	削除するか具体的に述べる
「極めて」	削除するか具体的に述べる
「絶対に」	削除
「基本的に」	削除(必要だと感じるなら、明確に説明できていない)
「本質的に」	削除するか、直接説明する
「とても」	削除するか、より強い言葉を使う
「本当に」	削除
「実際に」	削除(誤解を正す場合を除く)
「実のところ」	削除(単に事実を述べる)
「興味深いことに」	削除(興味深いかどうかは読者が決める)

堅苦しい/形式的な表現

形式的な学術調の表現を会話的な言い回しに置き換えてください:

❌ 堅苦しい	✓ 会話的
「〜であることに留意すべきである」	「〜に注意」または単にそのまま述べる
「〜と疑問に思うかもしれない」	「〜と疑問に思うかもしれません」
「これにより開発者は〜できる」	「これで〜できます」
「前述の」	「これ」または名前を再度挙げる
「続いて」	「次に」または「その後」
「利用する」	「使う」
「開始する」	「始める」
「〜の前に」	「〜する前に」
「〜という事態の場合には」	「もし〜なら」
「かなりの量の」	「たくさんの」または「多くの」

遊び心のある表現(控えめに使う)

内容が機械的に感じられないよう、時折人間味のある表現を加えてください。ただしやり過ぎないように:

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

ガイドライン:

• 主要なセクションごとに1〜2つの遊び心のある表現で十分
• ユーモアは内容から自然に生まれるべき
• 本文中の絵文字は避ける(コメント内では時折使ってもよい)
• 自分のジョークを説明しない
• 遊び心のある一文がうまく機能しないなら、ただ直接的に述べる

ページ構成(これに正確に従うこと)

すべてのコンセプトページは、この構造にこの正確な順序で従う必要があります:

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

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

[Immediately show a simple code example demonstrating the concept]

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

[学ぶ内容につながる簡潔な説明。重要な用語には インラインMDNリンク を付ける]

**このガイドで学ぶこと:** - 主要な学習成果 1 - 主要な学習成果 2 - 主要な学習成果 3 - 主要な学習成果 4(5〜7項目を目指す) [任意: 前提条件または重要な注意事項 - Infoボックスの後に配置] **前提条件:** このガイドは [関連コンセプト](/concepts/related-concept) を理解していることを前提としています。まだよく分からない場合は、先にそのガイドを読んでください!

---

[最初の主要セクション - 例: 「Xとは?」]

[新しく導入される用語/APIにはインラインMDNリンクを付けた中核的な説明]

[任意: このセクションのMDNリファレンスリンクを含むCardGroup]

---

[類推セクション - 例: 「レストランの類推」]

[コンセプトを理解させる身近な実世界の類推]

[コンセプトを視覚化するASCIIアート図]

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

---

[中核コンセプトセクション]

[コード例、表、Mintlifyコンポーネントを使った詳細解説]

最初のステップの説明 2番目のステップの説明 コード例を含む詳細な説明 コード例を含む詳細な説明 **簡単な経験則:** [覚えやすいまとめや語呂合わせ]

---

[API/実装セクション]

[コード内で実際にコンセプトを使う方法]

基本的な使い方

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

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

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

[高度なパターン]

// More complex real-world example

---

[よくある間違いセクション - 例: 「Fetchの最大の間違い」]

[開発者が最もよくする間違いを強調する]

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

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

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

**落とし穴:** [何がうまくいかず、なぜそうなるのかの明確な説明]

---

[高度なパターンセクション]

[実世界のパターンとベストプラクティス]

パターン名

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

// Usage
const result = await realWorldExample()

---

重要なポイント

**覚えておくべき重要なポイント：**

1. 最初の重要なポイント — 簡単な説明

2. 2つ目の重要なポイント — 簡単な説明

3. 3つ目の重要なポイント — 簡単な説明

4. 4つ目の重要なポイント — 簡単な説明

5. 5つ目の重要なポイント — 簡単な説明

[すべてを要約する重要なポイントを8～10個挙げてください]

---

理解度を確認する

**回答：**

[分かりやすい説明]

```javascript
// 回答を示すコード例
```

**回答：**

[必要に応じてコードを含む、分かりやすい説明]

[主なトピックを網羅する質問を5～6個挙げてください]

---

関連する概念

この概念との関連性 この概念との関連性

---

参考資料

主要な概念に関するMDNの公式ドキュメント 追加のMDNリファレンス

記事

この記事で読者が学べる内容の簡単な説明。 [質の高い記事を4～6件挙げてください]

動画

動画の内容の簡単な説明。 [質の高い動画を3～4本挙げてください] ```

---

SEO Guidelines

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

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

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

---

Target Keywords for Each Concept

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

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

More Keyword Cluster Examples:

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

---

Title Tag Optimization

The frontmatter has two title fields:

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

The Two-Title Pattern:

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

• title はSEOキーワードを配置するため、末尾を「in JavaScript」にします
• sidebarTitle はナビゲーションをすっきりさせるため、「JavaScript」を省きます

ルール：

1. title の理想的な長さは50～60文字です（Googleは長いタイトルを途中で切り捨てます）
2. 概念名を先頭にする — トピックから始め、「JavaScript」は末尾に置きます
3. 読者の関心を引く要素を加える — 読者が何を理解できるようになるか、何ができるようになるかを示します
4. 具体的にする — 汎用的なタイトルは検索順位が上がりません

効果的なタイトルの形式：

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

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

タイトルの例：

❌ 悪い例	✓ title（SEO）	✓ sidebarTitle（ナビゲーション）
"Closures"	"Closures: How Functions Remember Their Scope in JavaScript"	"Closures: How Functions Remember Their Scope"
"DOM"	"DOM: How Browsers Represent Web Pages in JavaScript"	"DOM: How Browsers Represent Web Pages"
"Promises"	"Promises: Handling Async Operations in JavaScript"	"Promises: Handling Async Operations"
"Call Stack"	"Call Stack: How Function Execution Works in JavaScript"	"Call Stack: How Function Execution Works"
"Event Loop"	"Event Loop: How Async Code Actually Runs in JavaScript"	"Event Loop: How Async Code Actually Runs"
"Scope"	"Scope and Closures: Variable Visibility in JavaScript"	"Scope and Closures: Variable Visibility"
"this"	"this: How Context Binding Works in JavaScript"	"this: How Context Binding Works"
"Prototype"	"Prototype Chain: Understanding Inheritance in JavaScript"	"Prototype Chain: Understanding Inheritance"

文字数の確認： 最終決定の前に、title の長さを確認してください。

• 50文字未満：説明的な情報をさらに加えることを検討してください
• 50～60文字：最適な長さです
• 60文字超：検索結果で途中までしか表示されないため、短くしてください

---

メタディスクリプションの最適化

description フィールドはメタディスクリプションになります。これは、検索結果に表示されるスニペットです。魅力的な説明文は、クリック率を高めます。

ルール：

1. 最大150～160文字（Google はこれより長い説明文を途中で切り詰めます）
2. 主要キーワードを前半に含める
3. 余裕があれば副次キーワードを自然に含める
4. 行動を促す言葉で始める — 「Learn」「Understand」「Discover」（AI が生成したように聞こえる「Master」は避ける）
5. 具体的な価値を示す — 何を学べるのでしょうか？
6. 興味を引く言葉で締めくくる — クリックする理由を示しましょう

説明文の定型：

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

説明文の例：

概念	❌ 短すぎる（クリック率が低い）	✓ SEO に最適化（150～160文字）
DOM	"Understanding the DOM"	"Learn how the DOM works in JavaScript. Understand how browsers represent HTML as a tree, select and manipulate elements, traverse nodes, and optimize rendering."
クロージャ	"Functions that remember"	"Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns."
Promise	"Async JavaScript"	"Understand JavaScript Promises for handling asynchronous operations. Learn to create, chain, and combine Promises, handle errors properly, and write cleaner async code."
イベントループ	"How async works"	"Discover how the JavaScript event loop manages async code execution. Understand the call stack, task queue, microtasks, and why JavaScript is single-threaded but non-blocking."
コールスタック	"Function execution"	"Learn how the JavaScript call stack tracks function execution. Understand stack frames, execution context, stack overflow errors, and how recursion affects the stack."
this	"Understanding this"	"Learn the 'this' keyword in JavaScript and how context binding works. Covers the four binding rules, arrow function behavior, and how to use call, apply, and bind."

文字数の確認：

• 120文字未満：価値を十分に伝えられていません。具体的な内容を追加しましょう
• 150～160文字：最適な長さ
• 160文字超：途中で切り詰められます。徹底的に推敲しましょう

---

キーワードの配置戦略

キーワードは戦略的な場所に含める必要があります。ただし、常に自然な形で使用してください。キーワードの詰め込みはランキングに悪影響を与えます。

優先的に配置する場所：

優先度	場所	含め方
🔴 重要	タイトル	主要キーワードを前半に含める
🔴 重要	メタディスクリプション	主要キーワードと副次キーワード1～2個
🔴 重要	最初の段落	最初の100語以内に自然な形で含める
🟠 高	H2 見出し	キーワードを含む質問形式の見出し
🟠 高	「学べる内容」ボックス	トピックに関連するフレーズ
🟡 中	H3 小見出し	関連キーワードや概念
🟡 中	重要なポイント	主要キーワードを自然に再度含める
🟢 良	代替テキスト	画像を使う場合はキーワードを含める

例：DOM ページでのキーワード配置

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

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

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

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

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

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

## DOM Manipulation Methods                                       ← 🟡 H3 with related keyword

## Key Takeaways                                                  ← 🟡 Reinforce in summary

キーワードの詰め込みを示す警告サイン：

• 同じ完全一致のフレーズが、1000語あたり3～4回を超えて使われている
• キーワードを無理に入れたため、文が不自然になっている
• 代名詞（「it」「they」「this」）が自然な箇所でキーワードを使っている

---

検索意図への対応

Google は、ユーザーの検索クエリに直接回答するページを上位に表示します。検索意図をすぐに満たせるよう、コンテンツを構成してください。

最初の段落のルール：

H2 の後に続く最初の段落では、暗に示された質問に直接答えましょう。答えに向けて話を進めるのではなく、最初に答えを提示してください。

## What is the Event Loop?

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


## What is the Event Loop?

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

質問形式の H2 見出し：

ユーザーの検索方法に合った H2 を使いましょう。

検索クエリ	使用する H2
"what is the DOM"	## What is the DOM?
"how closures work"	## How Do Closures Work?
"why use promises"	## Why Use Promises?
"when to use async await"	## When Should You Use async/await?

---

強調スニペットの最適化

強調スニペットは検索順位の0位、つまり通常の検索結果より上に表示されます。獲得を目指して、コンテンツを構成しましょう。

スニペットの種類と獲得方法：

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

パターン1：定義スニペット（40～60語）

「[概念]とは何か」というクエリの場合：

## What is a Closure in JavaScript?

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

これが効果的な理由：

• H2が検索クエリと完全に一致している
• 最初の文にキーワードを太字で記載している
• 40～60語で定義が完結している
• 「何か」だけでなく「なぜか」も説明している

パターン2：リストスニペット（手順）

「[操作]の方法」というクエリの場合：

## How to Make a Fetch Request in JavaScript

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

パターン3：表スニペット（比較）

「[X]と[Y]の比較」というクエリの場合：

## == vs === in JavaScript

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

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

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

For "types of [concept]" queries:

```mdx
## Types of Scope in JavaScript

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

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

---

SEOを考慮したコンテンツ構成

コンテンツの構成は、検索順位とユーザー体験の両方に影響します。

逆ピラミッド型：

最も重要な情報を最初に配置します。検索エンジンもユーザーも、質問にすぐ答えるコンテンツを好みます。

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

読みやすいコンテンツのパターン：

Googleは、流し読みしやすいコンテンツを高く評価します。次の要素を活用しましょう。

要素	SEO上のメリット	使用する場面
短い段落	直帰率を下げる	常に使用（最大2～4文）
箇条書き	強調スニペットに採用されやすい	3項目以上のリスト
番号付きリスト	「方法」を示すスニペットになりやすい	順序のある手順
表	スニペットに採用される可能性が高い	比較、参照データ
太字	クローラーにキーワードを示す	重要な用語を初めて記載するとき
見出し（H2/H3）	Googleに構成を伝える	大きなトピックが変わるたびに使用

コンテンツの長さの目安：

長さ	評価	対応
1,000語未満	内容が薄すぎる	詳細、例、例外的なケースを追加する
1,000～1,500語	最低限の水準	単純な概念であれば許容範囲
1,500～2,500語	良好	ほとんどの概念ページで標準的
2,500～4,000語	優秀	包括的なガイドに最適
4,000語超	要検討	複数のページに分割することを検討する

注： 長さだけでは検索順位は保証されません。すべてのセクションで価値を提供しましょう。内容を水増ししないでください。

---

SEOのための内部リンク

内部リンクは、検索エンジンがサイト構造を理解し、ページの評価を分配するのに役立ちます。

トピッククラスター戦略：

概念ページを相互につながるネットワークとして捉えましょう。それぞれの概念から、関連する3～5個の概念へリンクします。

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

リンク配置のガイドライン：

1. 前提条件（警告ボックス）：

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

2. 本文（自然な文脈）：

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

3. 関連概念のセクション：

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

アンカーテキストのベストプラクティス：

❌ 悪いアンカーテキスト	✓ 良いアンカーテキスト	理由
「ここをクリック」	「イベントループのガイド」	説明的で、キーワードを含んでいる
「この記事」	「Promisesの概念」	Googleにページの内容を伝える
「ここ」	「JavaScriptのクロージャ」	アンカーテキストにキーワードを含んでいる
「続きを読む」	「コールスタックを理解する」	自然で、情報が伝わる

---

URLとスラッグのベストプラクティス

URL（スラッグ）は影響こそ小さいものの、意味のある検索順位要因です。

ルール：

1. 小文字を使う — Closures ではなく closures
2. ハイフンを使う — call_stack や callstack ではなく call-stack
3. 短くする — 最大3～5語を目安にする
4. 主要キーワードを含める — 概念名を含める
5. ストップワードを避ける — 必要な場合を除き、「the」「and」「in」「of」は省く

スラッグの例：

概念	❌ 避ける	✓ 使用する
The Event Loop	the-event-loop	event-loop
this, call, apply and bind	this-call-apply-and-bind	this-call-apply-bind
Scope and Closures	scope-and-closures	scope-and-closures（許容範囲）または scope-closures
DOM and Layout Trees	dom-and-layout-trees	dom または dom-layout-trees

注： このプロジェクトでは、スラッグはすでに設定されています。新しいページを作成するときは、これらの規則に従ってください。

---

冒頭の段落：SEO の大きな効果

冒頭の段落は、SEO にとって特に重要な部分です。次の点を意識してください。

1. 読者が抱いている疑問を使って関心を引きます
2. 主要なキーワードを自然に含めます
3. 簡単な定義または回答を示します
4. この記事で学べる内容につなげます

テンプレート：

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

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

```javascript
// Immediately show a simple example

「この記事で学べること」のボックスへ簡単につなぐ文章

**Example (Closures):**

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

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

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

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

クロージャを理解すると、プライベート変数、ファクトリー関数、モジュールパターンなど、現代の JavaScript を支えるパターンを活用できるようになります。

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

---

## Inline Linking Rules (Critical!)

### Always Link to MDN

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

```mdx

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

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

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


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

関連する概念のページへのリンク

ほかのページで解説している概念に触れる場合は、そのページにリンクしてください。

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

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


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

MDN の一般的なリンクパターン

概念	MDN の URL パターン
Web API	https://developer.mozilla.org/en-US/docs/Web/API/{APIName}
JavaScript オブジェクト	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}
HTTP	https://developer.mozilla.org/en-US/docs/Web/HTTP
HTTP メソッド	https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/{METHOD}
HTTP ヘッダー	https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers

---

コード例のベストプラクティス

1. 可能な限りシンプルな例から始める

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

2. 手順ごとのコメントを付ける

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

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

3. コメントに出力を示す

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

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

4. 誤ったパターンと正しいパターンに ❌ と ✓ を使う

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

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

5. 意味の分かる変数名を使う

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

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

6. シンプルな内容から複雑な内容へ進める

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

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

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

---

リソース選定のガイドライン

外部リソース（記事、動画）は有益ですが、品質基準を満たす必要があります。

品質基準

次の条件を満たすリソースのみを掲載してください。

1. JavaScript に焦点を当てている — 概念が似ていても、主にほかの言語（C#、Python、Java など）を扱うリソースは含めません
2. 現在もアクセス可能である — 公開前にすべてのリンクが機能することを確認します
3. 高品質である — 信頼できる情報源（MDN、javascript.info、freeCodeCamp、著名な教育者など）から選びます
4. 最新である — 古いリソースは避け、時事性のあるトピックでは公開日を確認します
5. 正確である — アンチパターンを教えていないことを確認するため、内容に目を通します

リソースの説明文を書く

各リソースには、その独自性を説明する具体的で興味を引く2文の説明文が必要です。一般的な説明では、読者の時間を無駄にしてしまいます。

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


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


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


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


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

説明文の作成方法：

1. 1文目： リソースの独自性、または具体的な内容を説明します
2. 2文目： 読者がクリックすべき理由（得られるもの、最適な読者層、際立った点）を説明します

説明文で避ける表現：

• 「包括的なガイド……」（曖昧）
• 「素晴らしいチュートリアル……」（曖昧）
• 「……についてすべて学ぶ」（曖昧）
• 「知っておくべきことをすべて網羅……」（陳腐）

推奨する情報源

記事（優先）：

情報源	理由
javascript.info	内容が充実しており、よく更新され、演習も含まれています
MDN Web Docs	公式リファレンスで、常に正確です
freeCodeCamp	初心者に分かりやすく、実践的なチュートリアルがあります
dev.to（Lydia Hallie など）	視覚的な解説があり、コミュニティで人気があります
CSS-Tricks	DOM、ブラウザー API、視覚的なトピックに強みがあります

動画（優先）：

制作者	スタイル
Web Dev Simplified	明快で、初心者に分かりやすく、簡潔です
Fireship	テンポが速く、現代的で、楽しめます
Traversy Media	内容が充実した速習コースです
Fun Fun Function	個性豊かな掘り下げ解説です
Wes Bos	実践的で、実世界を重視しています

避けるもの：

• 概念が重なっていても、ほかのプログラミング言語（C#、Python、Java）を扱うリソース
• 古いチュートリアル（現代的な概念を ES6 以前の構文で解説するもの）
• 有料コンテンツ（無料プランがある場合を除く）
• 品質の低い Medium の記事（反応や正確さを確認してください）
• アンチパターンを教えるリソース
• 2 時間を超える動画（価値がある場合は、該当するタイムスタンプにリンクしてください）

リソースの確認

リソースを含める前に、次のことを確認してください。

1. リンクをクリックする — リンクが読み込まれ、ペイウォールの内側にないことを確認します
2. 内容にざっと目を通す — 正確で、適切に書かれていることを確認します
3. 日付を確認する — 時間とともに変わるトピックでは、最近のコンテンツを優先します
4. コメントやリアクションを読む — コミュニティからのフィードバックで、品質上の問題がわかります
5. コード例をテストする — コードが含まれている場合は、動作することを確認します

---

ASCII アート図

ASCII アートを使って概念を視覚化します。枠で囲み、ラベルを付けてください。

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

---

Mintlify コンポーネントのリファレンス

コンポーネント	使用する場面
<Info>	「学べること」ボックス、重要なポイント
<Warning>	よくある間違い、注意点、前提条件
<Tip>	上級者向けのヒント、経験則、ベストプラクティス
<Note>	補足情報、補足事項
<AccordionGroup>	展開可能なコンテンツ、Q&A セクション、任意の詳細解説
<Tabs>	異なるアプローチを並べて比較する場合
<Steps>	順を追った手順、番号付きのワークフロー
<CardGroup>	リソースへのリンク（記事、動画、参考資料）
<Card>	アイコンとリンク付きの個別リソース

カードアイコンのリファレンス

コンテンツの種類	アイコン
MDN／公式ドキュメント	book
記事／ブログ投稿	newspaper
動画	video
コース	graduation-cap
関連概念	内容に適したもの（handshake、hourglass、arrows-spin、sitemap など）

---

品質チェックリスト

概念ページを完成させる前に、次の項目をすべて確認してください。

構成

• 読者の興味を引く問いかけで始まっている
• 冒頭の直後に、簡単なコード例を示している
• 冒頭の直後に「学べること」の Info ボックスがある
• 主要なセクションが --- の水平線で区切られている
• ASCII アート図を使った、現実世界のたとえがある
• 「よくある間違い」または「最もよくある間違い」のセクションがある
• 8～10項目をまとめた「重要なポイント」セクションがある
• 5～6個の Q&A を含む「理解度チェック」セクションがある
• 関連概念、リファレンス、記事、動画の順で締めくくっている

リンク

• 新しい Web API／メソッドはすべて、初出時に MDN へのインラインリンクがある
• 関連概念はすべて、それぞれの概念ページ（/concepts/slug）にリンクしている
• リファレンスセクションに複数の MDN リンクがある
• 説明付きの質の高い記事が 4～6 件ある
• 説明付きの質の高い動画が 3～4 本ある

コード例

• 最初のコード例が非常にシンプルである
• 複雑な例に、手順ごとのコメントを使っている
• コメントで出力を示している（// "result"）
• 誤ったパターン／正しいパターンに ❌ と ✓ を使っている
• 意味がわかりやすい変数名を使っている
• シンプルな例から複雑な例へと段階的に進んでいる

コンテンツの品質

• コーディング初心者かもしれない読者を想定して書かれている
• 前提条件が Warning コンポーネントで示されている
• 事前知識を前提とする箇所には、リンクが用意されている
• すぐに参照できる情報には表を使っている
• 視覚的な概念には ASCII 図を使っている

言語の品質

• 説明文が「Learn」または「Understand」で始まり、「Master」では始まっていない
• ダッシュの多用を避けている（「重要なポイント」および構造化されたセクション以外では 15 個未満）
• AI に関する誇張表現がない：「劇的に」、「根本的に」、「信じられないほど」、「極めて」
• 堅苦しい表現がない：「最も重要なものの一つ」、「不可欠なポイント」、「留意すべき点」
• 強調表現に変化をつけている（すべてが「重要な洞察：」や「ベストプラクティス：」になっていない）
• 遊び心のある表現を控えめに使っている（主要セクションごとに最大 1～2 個）
• 余計な言葉がない：「基本的に」、「本質的に」、「実際には」、「非常に」、「本当に」
• 文章が簡潔である（「～するために」、「～という事実により」を使っていない）

リソースの品質

• すべての記事／動画のリンクが正常に機能することを確認済み
• すべてのリソースがJavaScriptに特化している（C#、Python、Javaのリソースは含めない）
• 各リソースに具体的な2文の説明がある（一般的な説明ではない）
• リソースの説明で、それぞれの独自性がわかる
• 古いリソースがない（時期によって内容が変わるトピックは公開日を確認）
• 信頼できる情報源の記事が4～6件
• 質の高いクリエイターによる動画が3～4本

---

テストの作成

コード例を追加する際は、/tests/に対応するテストを作成します。

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

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

---

SEO チェックリスト

概念ページを公開する前に、次の項目を確認してください。

タイトルとメタディスクリプション

• タイトルは50～60文字 — 文字数カウンターで確認する
• タイトルの末尾は「in JavaScript」 — SEOキーワードを最後に配置する
• タイトルに惹きつける要素がある — 読者が何を理解できるのかを伝える
• sidebarTitleは「in JavaScript」を除いたタイトルと一致する — ナビゲーションをすっきりさせる
• 説明文は150～160文字 — 価値を十分に伝える
• 説明文の最初の文に主要キーワードを含める
• 副次キーワードを1～2個、自然に含める
• 説明文は行動を促す言葉で始める（Learn、Understand、Discoverなど。「Master」は避ける）
• 説明文で具体的な価値を示す — 読者が何を学べるのかを伝える

キーワードの配置

• タイトルに主要キーワードを含める
• 説明文に主要キーワードを含める
• 最初の段落（冒頭100語以内）に主要キーワードを含める
• 少なくとも1つのH2見出しに主要キーワードを含める
• 自然な箇所で、H2／H3見出しに副次キーワードを含める
• 「学べること」ボックスの項目にキーワードを含める
• キーワードを詰め込みすぎない — コンテンツが自然に読めること

コンテンツの構成

• 検索意図に合った問いかけで始める
• 最初の200語以内にコード例を示す
• H2見出しの後の最初の段落で、想定される質問に直接答える
• コンテンツが1,500語以上（網羅的に解説する）
• 段落を短くする（最大2～4文）
• 関連項目が3つ以上ある場合は箇条書きを使う
• 手順が順番に並ぶ場合は番号付きリストを使う
• 比較や参考データには表を使う
• 重要な用語は初出時に太字にし、MDNへのリンクを付ける

フィーチャードスニペットの最適化

• 「Xとは」セクションに40～60語の定義段落を含める
• 「方法」セクションでは番号付き手順または<Steps>コンポーネントを使う
• 比較セクションでは、わかりやすい見出しの表を使う
• 検索クエリに合った疑問文形式のH2見出しを少なくとも1つ含める

内部リンク

• 本文で関連する概念ページに3～5件リンクする
• 説明的なアンカーテキストを使う（「ここをクリック」や「ここ」は避ける）
• 冒頭のWarningコンポーネントで前提条件にリンクする
• 関連概念セクションに、関連する概念のカードを4つ配置する
• リンクを自然な文脈で配置する — 無理に挿入しない

技術的なSEO

• スラッグは小文字とハイフンを使用する
• スラッグに主要キーワードを含める
• スラッグは最大3～5語にする
• すべての外部リンクに適切なURLを使う（リンク切れがないこと）
• MDNリンクが最新であることを確認する（リンク先が表示されることを確認）