seo-review by leonardomso/33-js-concepts
npx skills add https://github.com/leonardomso/33-js-concepts --skill seo-review使用此技能对 33 JavaScript Concepts 项目的概念文档页面进行有针对性的 SEO 审计。目标是最大化 JavaScript 开发者的搜索可见性。
每个概念页面应能针对以下类型的搜索进行排名:
遵循以下五个步骤完成完整的 SEO 审计。
审计前,确定该概念的关键词集群。
| 类型 | 模式 | 示例(闭包) |
|---|---|---|
| 主要 | [concept] JavaScript | closures JavaScript |
| What is | what is [concept] in JavaScript | what is a closure in JavaScript |
广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
| how does [concept] work |
| how do closures work |
| How to | how to use/create [concept] | how to use closures |
| Why | why use [concept] | why use closures JavaScript |
| Examples | [concept] examples | closure examples JavaScript |
| vs | [concept] vs [related] | closures vs scope |
| Interview | [concept] interview questions | closure interview questions |
系统地检查所有页面 SEO 元素。
验证内容结构是否有利于赢得精选摘要。
检查内部链接结构。
使用报告模板记录发现。
为每个概念使用这些预构建的关键词集群。
---|---|---|---
1 | 长度 50-60 字符 | 1 | 统计 title frontmatter 中的字符数
2 | 主要关键词在前半部分 | 1 | 概念名称出现较早
3 | 以 "in JavaScript" 结尾 | 1 | 检查标题结尾
4 | 包含吸引人的钩子 | 1 | 向读者承诺价值/好处
评分:
标题公式:
[Concept]: [What You'll Understand] in JavaScript
良好示例:
| 概念 | 标题(含字符数) |
|---|---|
| Closures | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) |
| Event Loop | "Event Loop: How Async Code Actually Runs in JavaScript" (54 chars) |
| Promises | "Promises: Handling Async Operations in JavaScript" (49 chars) |
| DOM | "DOM: How Browsers Represent Web Pages in JavaScript" (51 chars) |
不良示例:
| 问题 | 不良标题 | 更好的标题 |
|---|---|---|
| 太短 | "Closures" | "Closures: How Functions Remember Their Scope in JavaScript" |
| 太长 | "Understanding JavaScript Closures and How They Work with Examples" (66 chars) | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) |
| 无钩子 | "JavaScript Closures" | "Closures: How Functions Remember Their Scope in JavaScript" |
| 缺少 "JavaScript" | "Understanding Closures and Scope" | 在末尾添加 "in JavaScript" |
---|---|---|---
1 | 长度 150-160 字符 | 1 | 统计 description frontmatter 中的字符数
2 | 以行动词开头 | 1 | "Learn", "Understand", "Discover" (NOT "Master")
3 | 包含主要关键词 | 1 | 概念名称 + "JavaScript" 存在
4 | 承诺具体价值 | 1 | 列出读者将学到什么
描述公式:
[Action word] [what it is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3].
良好示例:
| 概念 | 描述 |
|---|---|
| Closures | "Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns." (159 chars) |
| Event Loop | "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." (176 chars - trim!) |
| 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." (162 chars) |
不良示例:
| 问题 | 不良描述 | 修复方法 |
|---|---|---|
| 太短 | "Learn about closures" | 扩展到 150-160 字符并包含具体内容 |
| 以 "Master" 开头 | "Master JavaScript closures..." | "Learn JavaScript closures..." |
| 太模糊 | "A guide to closures" | 列出涵盖的具体主题 |
| 缺少关键词 | "Functions can remember things" | 包含 "closures" 和 "JavaScript" |
---|---|---|---
1 | 主要关键词在标题中 | 1 | 检查 frontmatter title
2 | 主要关键词在元描述中 | 1 | 检查 frontmatter description
3 | 主要关键词在前 100 词中 | 1 | 检查开篇段落
4 | 关键词在至少一个 H2 标题中 | 1 | 扫描所有 ## 标题
5 | 无关键词堆砌 | 1 | 内容读起来自然
关键词布局图:
┌─────────────────────────────────────────────────────────────────────────┐
│ KEYWORD PLACEMENT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 🔴 CRITICAL (Must have keyword) │
│ ───────────────────────────────── │
│ • title frontmatter │
│ • description frontmatter │
│ • First paragraph (within 100 words) │
│ • At least one H2 heading │
│ │
│ 🟡 RECOMMENDED (Include naturally) │
│ ────────────────────────────────── │
│ • "What you'll learn" Info box │
│ • H3 subheadings │
│ • Key Takeaways section │
│ • First sentence after major H2s │
│ │
│ ⚠️ AVOID │
│ ───────── │
│ • Same phrase >4 times per 1000 words │
│ • Forcing keywords where pronouns work better │
│ • Awkward sentence structures to fit keywords │
│ │
└─────────────────────────────────────────────────────────────────────────┘
---|---|---|---
1 | 以问题钩子开头 | 1 | 第一段提出引人入胜的问题
2 | 前 200 词内有代码示例 | 1 | 早期出现简单示例
3 | "What you'll learn" 信息框 | 1 | 开篇后有 <Info> 组件
4 | 短段落(2-4 句) | 1 | 扫描内容中的长段落块
5 | 1,500+ 词 | 1 | 词数检查
6 | 关键术语首次提及加粗 | 1 | 重要术语使用 **bold**
内容结构模板:
┌─────────────────────────────────────────────────────────────────────────┐
│ IDEAL PAGE STRUCTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. QUESTION HOOK (First 50 words) │
│ "How does JavaScript...? Why do...?" │
│ │
│ 2. BRIEF ANSWER + CODE EXAMPLE (Words 50-200) │
│ Quick explanation + simple code demo │
│ │
│ 3. "WHAT YOU'LL LEARN" INFO BOX │
│ 5-7 bullet points │
│ │
│ 4. PREREQUISITES WARNING (if applicable) │
│ Link to required prior concepts │
│ │
│ 5. MAIN CONTENT SECTIONS (H2s) │
│ Each H2 answers a question or teaches a concept │
│ Include code examples, diagrams, tables │
│ │
│ 6. COMMON MISTAKES / GOTCHAS SECTION │
│ What trips people up │
│ │
│ 7. KEY TAKEAWAYS │
│ 8-10 numbered points summarizing everything │
│ │
│ 8. TEST YOUR KNOWLEDGE │
│ 5-6 Q&A accordions │
│ │
│ 9. RELATED CONCEPTS │
│ 4 cards linking to related topics │
│ │
│ 10. RESOURCES (Reference, Articles, Videos) │
│ MDN links, curated articles, videos │
│ │
└─────────────────────────────────────────────────────────────────────────┘
---|---|---|---
1 | "What is X" 有 40-60 词的定义 | 1 | 统计 "What is" H2 后第一段的词数
2 | 至少一个 H2 以问题形式表述 | 1 | 检查是否有 "What is", "How does", "Why" H2s
3 | "How to" 内容有编号步骤 | 1 | 使用 <Steps> 组件或编号列表
4 | 对比表格(如适用) | 1 | "X vs Y" 内容使用表格
精选摘要模式:
┌─────────────────────────────────────────────────────────────────────────┐
│ FEATURED SNIPPET FORMATS │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ QUERY TYPE WINNING FORMAT YOUR CONTENT │
│ ─────────── ────────────── ──────────── │
│ │
│ "What is X" Paragraph 40-60 word definition │
│ after H2, bold keyword │
│ │
│ "How to X" Numbered list <Steps> component or │
│ 1. 2. 3. markdown │
│ │
│ "X vs Y" Table | Feature | X | Y | │
│ comparison table │
│ │
│ "Types of X" Bullet list - **Type 1** — desc │
│ - **Type 2** — desc │
│ │
│ "[X] examples" Code block ```javascript │
│ + explanation // example code │
│ │
└─────────────────────────────────────────────────────────────────────────┘
定义段落示例(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.
(这是 52 个词 - 非常适合精选摘要)
---|---|---|---
1 | 正文中链接了 3-5 个相关概念 | 1 | 统计正文中的 /concepts/ 链接数
2 | 描述性锚文本 | 1 | 没有 "click here", "here", "this"
3 | 警告框中的先决条件 | 1 | 开头有带链接的 <Warning>
4 | 相关概念部分有 4 张卡片 | 1 | 末尾有包含 4 张 Card 的 <CardGroup>
良好锚文本:
| ❌ 不良 | ✓ 良好 |
|---|---|
| "click here" | "event loop concept" |
| "here" | "JavaScript closures" |
| "this article" | "our Promises guide" |
| "read more" | "understanding the call stack" |
链接布局策略:
<!-- 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 needed.
</Warning>
<!-- In Body Content (natural context) -->
When the callback finishes, it's added to the task queue — managed by
the [event loop](/concepts/event-loop).
<!-- In Related Concepts Section -->
<CardGroup cols={2}>
<Card title="Promises" icon="handshake" href="/concepts/promises">
async/await is built on top of Promises
</Card>
</CardGroup>
---|---|---|---
1 | 每页一个 H1 | 1 | 只有一个 # 标题(即标题)
2 | URL 别名包含关键词 | 1 | /concepts/closures 而不是 /concepts/topic-1
3 | 无孤立页面 | 1 | 页面至少被另一个页面链接
H1 规则:
每个页面应恰好有一个 H1(您的主标题)。这对 SEO 至关重要:
H1 告诉 Google 页面的主题
多个 H1 会让搜索引擎对页面层次结构感到困惑
所有其他标题应为 H2 (##) 及以下级别
H1 应包含您的主要关键词
URL/别名最佳实践:
| ✅ 良好 | ❌ 不良 |
|---|---|
/concepts/closures | /concepts/c1 |
/concepts/event-loop | /concepts/topic-7 |
/concepts/type-coercion | /concepts/abc123 |
/concepts/async-await | /concepts/async_await |
别名规则:
event-loop 而非 event_loop/concepts/Event-Loop 应为 /concepts/event-loop孤立页面检测:
孤立页面是指没有来自其他页面的内部链接指向它的页面。这会损害 SEO,因为:
如何检查孤立页面:
grep -r "/concepts/[slug]" docs/docs.json)修复孤立页面:
| 类别 | 最高分 |
|---|---|
| 标题标签 | 4 |
| 元描述 | 4 |
| 关键词布局 | 5 |
| 内容结构 | 6 |
| 精选摘要 | 4 |
| 内部链接 | 4 |
| 技术 SEO | 3 |
| 总计 | 30 |
| 分数 | 百分比 | 状态 | 行动 |
|---|---|---|---|
| 27-30 | 90-100% | ✅ 优秀 | 准备发布 |
| 23-26 | 75-89% | ⚠️ 良好 | 需要少量优化 |
| 17-22 | 55-74% | ⚠️ 一般 | 需要多处改进 |
| 0-16 | <55% | ❌ 差 | 需要大量改进 |
| 问题 | 当前情况 | 修复方法 |
|---|---|---|
| 太短 (<50 字符) | "Closures" (8) | "Closures: How Functions Remember Their Scope in JavaScript" (58) |
| 太长 (>60 字符) | "Understanding JavaScript Closures and How They Work with Examples" (66) | "Closures: How Functions Remember Their Scope in JavaScript" (58) |
| 缺少关键词 | "Understanding Scope" | 添加概念名称:"Closures: Understanding Scope in JavaScript" |
| 无钩子 | "JavaScript Closures" | 添加好处:"Closures: How Functions Remember Their Scope in JavaScript" |
| 缺少 "JavaScript" | "Closures Explained" | 在末尾添加:"Closures Explained in JavaScript" |
| 问题 | 当前情况 | 修复方法 |
|---|---|---|
| 太短 (<120 字符) | "Learn about closures" (20) | 扩展到 150-160 字符并包含具体内容 |
| 太长 (>160 字符) | [被截断] | 严格编辑,保留关键信息 |
| 以 "Master" 开头 | "Master JavaScript closures..." | "Learn JavaScript closures..." |
| 无关键词 | "Functions that remember" | 包含 "closures" 和 "JavaScript" |
| 太模糊 | "A guide to closures" | 列出具体主题:"Covers X, Y, and Z" |
| 问题 | 修复方法 |
|---|---|
| 无问题钩子 | 以 "How does...?" 或 "Why...?" 开头 |
| 代码示例太靠后 | 将简单示例移到前 200 词内 |
| 缺少信息框 | 添加带 "What you'll learn" 的 <Info> |
| 段落过长 | 分成 2-4 句的块 |
| 少于 1,500 词 | 增加深度、示例、边界情况 |
| 无加粗术语 | 首次提及关键概念时加粗 |
| 问题 | 修复方法 |
|---|---|
| 无 "What is" 定义 | 添加 40-60 词的定义段落 |
| 定义太长 | 压缩到 40-60 词 |
| 无问题式 H2 | 添加 "What is X?" 或 "How does X work?" H2 |
| 步骤未编号 | 使用 <Steps> 或编号 markdown |
| 无对比表格 | 为 "X vs Y" 部分添加表格 |
| 问题 | 修复方法 |
|---|---|
| 无内部链接 | 添加 3-5 个指向相关概念的链接 |
| 锚文本不良 | 将 "click here" 替换为描述性文本 |
| 无先决条件 | 添加带先决条件链接的 <Warning> |
| 相关概念部分为空 | 添加 4 张链接到相关主题的卡片 |
| 问题 | 修复方法 |
|---|---|
| 多个 H1 标签 | 只保留一个 # 标题(标题),所有分区使用 ## |
| 别名缺少关键词 | 重命名文件以包含概念名称(例如,closures.mdx) |
| 孤立页面 | 从相关概念页面的正文或相关概念部分添加链接 |
| 别名中使用下划线 | 使用连字符:event-loop.mdx 而非 event_loop.mdx |
| 别名中有大写字母 | 仅使用小写:async-await.mdx 而非 Async-Await.mdx |
| 别名太长 | 缩短为主要关键词:closures.mdx 而非 understanding-javascript-closures-and-scope.mdx |
使用此模板记录您的发现。
# SEO Audit Report: [Concept Name]
**File:** `/docs/concepts/[slug].mdx`
**Date:** YYYY-MM-DD
**Auditor:** [Name/Claude]
**Overall Score:** XX/30 (XX%)
**Status:** ✅ Excellent | ⚠️ Needs Work | ❌ Poor
---
## Score Summary
| Category | Score | Status |
|----------|-------|--------|
| Title Tag | X/4 | ✅/⚠️/❌ |
| Meta Description | X/4 | ✅/⚠️/❌ |
| Keyword Placement | X/5 | ✅/⚠️/❌ |
| Content Structure | X/6 | ✅/⚠️/❌ |
| Featured Snippets | X/4 | ✅/⚠️/❌ |
| Internal Linking | X/4 | ✅/⚠️/❌ |
| Technical SEO | X/3 | ✅/⚠️/❌ |
| **Total** | **X/30** | **STATUS** |
---
## Target Keywords
**Primary Keyword:** [e.g., "JavaScript closures"]
**Secondary Keywords:**
- [keyword 1]
- [keyword 2]
- [keyword 3]
**Search Intent:** Informational / How-to / Comparison
---
## Title Tag Analysis
**Current Title:** "[current title from frontmatter]"
**Character Count:** XX characters
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| Length 50-60 chars | ✅/❌ | XX characters |
| Primary keyword in first half | ✅/❌ | [notes] |
| Ends with "in JavaScript" | ✅/❌ | [notes] |
| Contains compelling hook | ✅/❌ | [notes] |
**Issues Found:** [if any]
**Recommended Title:** "[suggested title]" (XX chars)
---
## Meta Description Analysis
**Current Description:** "[current description from frontmatter]"
**Character Count:** XX characters
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| Length 150-160 chars | ✅/❌ | XX characters |
| Starts with action word | ✅/❌ | Starts with "[word]" |
| Contains primary keyword | ✅/❌ | [notes] |
| Promises specific value | ✅/❌ | [notes] |
**Issues Found:** [if any]
**Recommended Description:** "[suggested description]" (XX chars)
---
## Keyword Placement Analysis
**Score:** X/5
| Location | Present | Notes |
|----------|---------|-------|
| Title | ✅/❌ | [notes] |
| Meta description | ✅/❌ | [notes] |
| First 100 words | ✅/❌ | Found at word XX |
| H2 heading | ✅/❌ | Found in: "[H2 text]" |
| Natural reading | ✅/❌ | [no stuffing / stuffing detected] |
**Missing Keyword Placements:**
- [ ] [Location where keyword should be added]
---
## Content Structure Analysis
**Word Count:** X,XXX words
**Score:** X/6
| Check | Status | Notes |
|-------|--------|-------|
| Question hook opening | ✅/❌ | [notes] |
| Code in first 200 words | ✅/❌ | Code appears at word XX |
| "What you'll learn" box | ✅/❌ | [present/missing] |
| Short paragraphs | ✅/❌ | [notes on paragraph length] |
| 1,500+ words | ✅/❌ | X,XXX words |
| Bolded key terms | ✅/❌ | [notes] |
**Structure Issues:**
- [ ] [Issue and recommendation]
---
## Featured Snippet Analysis
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| 40-60 word definition | ✅/❌ | Currently XX words |
| Question-format H2 | ✅/❌ | Found: "[H2]" / Not found |
| Numbered steps | ✅/❌ | [notes] |
| Comparison tables | ✅/❌/N/A | [notes] |
**Snippet Opportunities:**
1. **"What is [concept]" snippet:**
- Current definition: XX words
- Action: [Expand to/Trim to] 40-60 words
2. **"How to [action]" snippet:**
- Action: [Add Steps component / Already present]
---
## Internal Linking Analysis
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| 3-5 internal links in body | ✅/❌ | Found X links |
| Descriptive anchor text | ✅/❌ | [notes] |
| Prerequisites in Warning | ✅/❌ | [present/missing] |
| Related Concepts section | ✅/❌ | X cards present |
**Current Internal Links:**
1. [Anchor text] → `/concepts/[slug]`
2. [Anchor text] → `/concepts/[slug]`
**Recommended Links to Add:**
- Link to [concept] in [section/context]
- Link to [concept] in [section/context]
**Bad Anchor Text Found:**
- Line XX: "click here" → change to "[descriptive text]"
---
## Technical SEO Analysis
**Score:** X/3
| Check | Status | Notes |
|-------|--------|-------|
| Single H1 per page | ✅/❌ | [Found X H1 tags] |
| URL slug contains keyword | ✅/❌ | Current: `/concepts/[slug]` |
| Not an orphan page | ✅/❌ | Linked from X other pages |
**H1 Tags Found:**
- Line XX: `# [H1 text]` ← Should be the only one
- [List any additional H1s that need to be changed to H2]
**Slug Analysis:**
- Current slug: `[slug].mdx`
- Contains keyword: ✅/❌
- Format correct: ✅/❌ (lowercase, hyphens, no special chars)
**Incoming Links Found:**
1. `/concepts/[other-concept]` → Links to this page in [section]
2. `/concepts/[other-concept]` → Links in Related Concepts
**If orphan page, add links from:**
- [Suggested concept page] in [section]
- [Suggested concept page] in Related Concepts
---
## Priority Fixes
### High Priority (Do First)
1. **[Issue]**
- Current: [what it is now]
- Recommended: [what it should be]
- Impact: [why this matters]
2. **[Issue]**
- Current: [what it is now]
- Recommended: [what it should be]
- Impact: [why this matters]
### Medium Priority
1. **[Issue]**
- Recommendation: [fix]
### Low Priority (Nice to Have)
1. **[Issue]**
- Recommendation: [fix]
---
## Competitive Analysis (Optional)
**Top-Ranking Pages for "[primary keyword]":**
1. **[Competitor 1 - URL]**
- What they do well: [observation]
- Word count: ~X,XXX
2. **[Competitor 2 - URL]**
- What they do well: [observation]
- Word count: ~X,XXX
**Our Advantages:**
- [What we do better]
**Gaps to Fill:**
- [What we're missing that competitors have]
---
## Implementation Checklist
After making fixes, verify:
- [ ] Title is 50-60 characters with keyword and hook
- [ ] Description is 150-160 characters with action word and value
- [ ] Primary keyword in title, description, first 100 words, and H2
- [ ] Opens with question hook
- [ ] Code example in first 200 words
- [ ] "What you'll learn" Info box present
- [ ] Paragraphs are 2-4 sentences
- [ ] 1,500+ words total
- [ ] Key terms bolded on first mention
- [ ] 40-60 word definition for featured snippet
- [ ] At least one question-format H2
- [ ] 3-5 internal links with descriptive anchor text
- [ ] Prerequisites in Warning box (if applicable)
- [ ] Related Concepts section has 4 cards
- [ ] Single H1 per page (title only)
- [ ] URL slug contains primary keyword
- [ ] Page linked from at least one other concept page
- [ ] All fixes implemented and verified
---
## Final Recommendation
**Ready to Publish:** ✅ Yes / ❌ No - [reason]
**Next Review Date:** [When to re-audit, e.g., "3 months" or "after major update"]
| 元素 | 理想长度 |
|---|---|
| 标题 | 50-60 字符 |
| 元描述 | 150-160 字符 |
| 定义段落 | 40-60 词 |
| 长度 | 评估 |
|---|---|
| <1,000 词 | 太单薄 - 增加深度 |
| 1,000-1,500 | 最低可行 |
| 1,500-2,500 | 良好 |
| 2,500-4,000 | 优秀 |
4,000 | 考虑拆分
对概念页面进行 SEO 审计时:
记住: SEO 不是关于玩弄搜索引擎 — 而是为了让需要它的开发者更容易找到内容。每一项优化也应改善读者的体验。
每周安装数
491
仓库
GitHub Stars
66.3K
首次出现
Jan 20, 2026
安全审计
安装于
opencode337
gemini-cli335
github-copilot313
codex309
claude-code294
cursor287
Use this skill to perform a focused SEO audit on concept documentation pages for the 33 JavaScript Concepts project. The goal is to maximize search visibility for JavaScript developers.
Each concept page should rank for searches like:
Follow these five steps for a complete SEO audit.
Before auditing, identify the keyword cluster for the concept.
| Type | Pattern | Example (Closures) |
|---|---|---|
| Primary | [concept] JavaScript | closures JavaScript |
| What is | what is [concept] in JavaScript | what is a closure in JavaScript |
| How does | how does [concept] work | how do closures work |
| How to | how to use/create [concept] | how to use closures |
| Why | why use [concept] | why use closures JavaScript |
| Examples | [concept] examples | closure examples JavaScript |
| vs | [concept] vs [related] | closures vs scope |
| Interview | [concept] interview questions | closure interview questions |
Check all on-page SEO elements systematically.
Verify content is structured to win featured snippets.
Check the internal link structure.
Document findings using the report template.
Use these pre-built keyword clusters for each concept.
---|---|---|---
1 | Length 50-60 characters | 1 | Count characters in title frontmatter
2 | Primary keyword in first half | 1 | Concept name appears early
3 | Ends with "in JavaScript" | 1 | Check title ending
4 | Contains compelling hook | 1 | Promises value/benefit to reader
Scoring:
Title Formula:
[Concept]: [What You'll Understand] in JavaScript
Good Examples:
| Concept | Title (with character count) |
|---|---|
| Closures | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) |
| Event Loop | "Event Loop: How Async Code Actually Runs in JavaScript" (54 chars) |
| Promises | "Promises: Handling Async Operations in JavaScript" (49 chars) |
| DOM | "DOM: How Browsers Represent Web Pages in JavaScript" (51 chars) |
Bad Examples:
| Issue | Bad Title | Better Title |
|---|---|---|
| Too short | "Closures" | "Closures: How Functions Remember Their Scope in JavaScript" |
| Too long | "Understanding JavaScript Closures and How They Work with Examples" (66 chars) | "Closures: How Functions Remember Their Scope in JavaScript" (58 chars) |
| No hook | "JavaScript Closures" | "Closures: How Functions Remember Their Scope in JavaScript" |
| Missing "JavaScript" | "Understanding Closures and Scope" | Add "in JavaScript" at end |
---|---|---|---
1 | Length 150-160 characters | 1 | Count characters in description frontmatter
2 | Starts with action word | 1 | "Learn", "Understand", "Discover" (NOT "Master")
3 | Contains primary keyword | 1 | Concept name + "JavaScript" present
4 | Promises specific value | 1 | Lists what reader will learn
Description Formula:
[Action word] [what it is] in JavaScript. [Specific things they'll learn]: [topic 1], [topic 2], and [topic 3].
Good Examples:
| Concept | Description |
|---|---|
| Closures | "Learn JavaScript closures and how functions remember their scope. Covers lexical scoping, practical use cases, memory considerations, and common closure patterns." (159 chars) |
| Event Loop | "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." (176 chars - trim!) |
| 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." (162 chars) |
Bad Examples:
| Issue | Bad Description | Fix |
|---|---|---|
| Too short | "Learn about closures" | Expand to 150-160 chars with specifics |
| Starts with "Master" | "Master JavaScript closures..." | "Learn JavaScript closures..." |
| Too vague | "A guide to closures" | List specific topics covered |
| Missing keyword | "Functions can remember things" | Include "closures" and "JavaScript" |
---|---|---|---
1 | Primary keyword in title | 1 | Check frontmatter title
2 | Primary keyword in meta description | 1 | Check frontmatter description
3 | Primary keyword in first 100 words | 1 | Check opening paragraphs
4 | Keyword in at least one H2 heading | 1 | Scan all ## headings
5 | No keyword stuffing | 1 | Content reads naturally
Keyword Placement Map:
┌─────────────────────────────────────────────────────────────────────────┐
│ KEYWORD PLACEMENT │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 🔴 CRITICAL (Must have keyword) │
│ ───────────────────────────────── │
│ • title frontmatter │
│ • description frontmatter │
│ • First paragraph (within 100 words) │
│ • At least one H2 heading │
│ │
│ 🟡 RECOMMENDED (Include naturally) │
│ ────────────────────────────────── │
│ • "What you'll learn" Info box │
│ • H3 subheadings │
│ • Key Takeaways section │
│ • First sentence after major H2s │
│ │
│ ⚠️ AVOID │
│ ───────── │
│ • Same phrase >4 times per 1000 words │
│ • Forcing keywords where pronouns work better │
│ • Awkward sentence structures to fit keywords │
│ │
└─────────────────────────────────────────────────────────────────────────┘
---|---|---|---
1 | Opens with question hook | 1 | First paragraph asks engaging question
2 | Code example in first 200 words | 1 | Simple example appears early
3 | "What you'll learn" Info box | 1 | <Info> component after opening
4 | Short paragraphs (2-4 sentences) | 1 | Scan content for long blocks
5 | 1,500+ words | 1 | Word count check
6 | Key terms bolded on first mention | 1 | Important terms use **bold**
Content Structure Template:
┌─────────────────────────────────────────────────────────────────────────┐
│ IDEAL PAGE STRUCTURE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ 1. QUESTION HOOK (First 50 words) │
│ "How does JavaScript...? Why do...?" │
│ │
│ 2. BRIEF ANSWER + CODE EXAMPLE (Words 50-200) │
│ Quick explanation + simple code demo │
│ │
│ 3. "WHAT YOU'LL LEARN" INFO BOX │
│ 5-7 bullet points │
│ │
│ 4. PREREQUISITES WARNING (if applicable) │
│ Link to required prior concepts │
│ │
│ 5. MAIN CONTENT SECTIONS (H2s) │
│ Each H2 answers a question or teaches a concept │
│ Include code examples, diagrams, tables │
│ │
│ 6. COMMON MISTAKES / GOTCHAS SECTION │
│ What trips people up │
│ │
│ 7. KEY TAKEAWAYS │
│ 8-10 numbered points summarizing everything │
│ │
│ 8. TEST YOUR KNOWLEDGE │
│ 5-6 Q&A accordions │
│ │
│ 9. RELATED CONCEPTS │
│ 4 cards linking to related topics │
│ │
│ 10. RESOURCES (Reference, Articles, Videos) │
│ MDN links, curated articles, videos │
│ │
└─────────────────────────────────────────────────────────────────────────┘
---|---|---|---
1 | "What is X" has 40-60 word definition | 1 | Count words in first paragraph after "What is" H2
2 | At least one H2 is phrased as question | 1 | Check for "What is", "How does", "Why" H2s
3 | Numbered steps for "How to" content | 1 | Uses <Steps> component or numbered list
4 | Comparison tables (if applicable) | 1 | Tables for "X vs Y" content
Featured Snippet Patterns:
┌─────────────────────────────────────────────────────────────────────────┐
│ FEATURED SNIPPET FORMATS │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ QUERY TYPE WINNING FORMAT YOUR CONTENT │
│ ─────────── ────────────── ──────────── │
│ │
│ "What is X" Paragraph 40-60 word definition │
│ after H2, bold keyword │
│ │
│ "How to X" Numbered list <Steps> component or │
│ 1. 2. 3. markdown │
│ │
│ "X vs Y" Table | Feature | X | Y | │
│ comparison table │
│ │
│ "Types of X" Bullet list - **Type 1** — desc │
│ - **Type 2** — desc │
│ │
│ "[X] examples" Code block ```javascript │
│ + explanation // example code │
│ │
└─────────────────────────────────────────────────────────────────────────┘
Definition Paragraph Example (40-60 words):
## 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.
(This is 52 words - perfect for a featured snippet)
---|---|---|---
1 | 3-5 related concepts linked in body | 1 | Count /concepts/ links in prose
2 | Descriptive anchor text | 1 | No "click here", "here", "this"
3 | Prerequisites in Warning box | 1 | <Warning> with links at start
4 | Related Concepts section has 4 cards | 1 | <CardGroup> at end with 4 Cards
Good Anchor Text:
| ❌ Bad | ✓ Good |
|---|---|
| "click here" | "event loop concept" |
| "here" | "JavaScript closures" |
| "this article" | "our Promises guide" |
| "read more" | "understanding the call stack" |
Link Placement Strategy:
<!-- 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 needed.
</Warning>
<!-- In Body Content (natural context) -->
When the callback finishes, it's added to the task queue — managed by
the [event loop](/concepts/event-loop).
<!-- In Related Concepts Section -->
<CardGroup cols={2}>
<Card title="Promises" icon="handshake" href="/concepts/promises">
async/await is built on top of Promises
</Card>
</CardGroup>
---|---|---|---
1 | Single H1 per page | 1 | Only one # heading (the title)
2 | URL slug contains keyword | 1 | /concepts/closures not /concepts/topic-1
3 | No orphan pages | 1 | Page is linked from at least one other page
H1 Rule:
Every page should have exactly ONE H1 (your main title). This is critical for SEO:
The H1 tells Google what the page is about
Multiple H1s confuse search engines about page hierarchy
All other headings should be H2 (##) and below
The H1 should contain your primary keyword
URL/Slug Best Practices:
| ✅ Good | ❌ Bad |
|---|---|
/concepts/closures | /concepts/c1 |
/concepts/event-loop | /concepts/topic-7 |
/concepts/type-coercion | /concepts/abc123 |
/concepts/async-await | /concepts/async_await |
Rules for slugs:
event-loop not event_loop/concepts/Event-Loop should be /concepts/event-loopOrphan Page Detection:
An orphan page has no internal links pointing to it from other pages. This hurts SEO because:
How to check for orphan pages:
grep -r "/concepts/[slug]" docs/docs.json)Fixing orphan pages:
| Category | Max Points |
|---|---|
| Title Tag | 4 |
| Meta Description | 4 |
| Keyword Placement | 5 |
| Content Structure | 6 |
| Featured Snippets | 4 |
| Internal Linking | 4 |
| Technical SEO | 3 |
| Total | 30 |
| Score | Percentage | Status | Action |
|---|---|---|---|
| 27-30 | 90-100% | ✅ Excellent | Ready to publish |
| 23-26 | 75-89% | ⚠️ Good | Minor optimizations needed |
| 17-22 | 55-74% | ⚠️ Fair | Several improvements needed |
| 0-16 | <55% | ❌ Poor | Significant work required |
| Issue | Current | Fix |
|---|---|---|
| Too short (<50 chars) | "Closures" (8) | "Closures: How Functions Remember Their Scope in JavaScript" (58) |
| Too long (>60 chars) | "Understanding JavaScript Closures and How They Work with Examples" (66) | "Closures: How Functions Remember Their Scope in JavaScript" (58) |
| Missing keyword | "Understanding Scope" | Add concept name: "Closures: Understanding Scope in JavaScript" |
| No hook | "JavaScript Closures" | Add benefit: "Closures: How Functions Remember Their Scope in JavaScript" |
| Missing "JavaScript" | "Closures Explained" | Add at end: "Closures Explained in JavaScript" |
| Issue | Current | Fix |
|---|---|---|
| Too short (<120 chars) | "Learn about closures" (20) | Expand with specifics to 150-160 chars |
| Too long (>160 chars) | [Gets truncated] | Edit ruthlessly, keep key information |
| Starts with "Master" | "Master JavaScript closures..." | "Learn JavaScript closures..." |
| No keyword | "Functions that remember" | Include "closures" and "JavaScript" |
| Too vague | "A guide to closures" | List specific topics: "Covers X, Y, and Z" |
| Issue | Fix |
|---|---|
| No question hook | Start with "How does...?" or "Why...?" |
| Code example too late | Move simple example to first 200 words |
| Missing Info box | Add <Info> with "What you'll learn" |
| Long paragraphs | Break into 2-4 sentence chunks |
| Under 1,500 words | Add more depth, examples, edge cases |
| No bolded terms | Bold key concepts on first mention |
| Issue | Fix |
|---|---|
| No "What is" definition | Add 40-60 word definition paragraph |
| Definition too long | Tighten to 40-60 words |
| No question H2s | Add "What is X?" or "How does X work?" H2 |
| Steps not numbered | Use <Steps> or numbered markdown |
| No comparison tables | Add table for "X vs Y" sections |
| Issue | Fix |
|---|---|
| No internal links | Add 3-5 links to related concepts |
| Bad anchor text | Replace "click here" with descriptive text |
| No prerequisites | Add <Warning> with prerequisite links |
| Empty Related Concepts | Add 4 Cards linking to related topics |
| Issue | Fix |
|---|---|
| Multiple H1 tags | Keep only one # heading (the title), use ## for all sections |
| Slug missing keyword | Rename file to include concept name (e.g., closures.mdx) |
| Orphan page | Add links from related concept pages' body or Related Concepts section |
| Underscore in slug | Use hyphens: event-loop.mdx not event_loop.mdx |
| Uppercase in slug | Use lowercase only: async-await.mdx not |
Use this template to document your findings.
# SEO Audit Report: [Concept Name]
**File:** `/docs/concepts/[slug].mdx`
**Date:** YYYY-MM-DD
**Auditor:** [Name/Claude]
**Overall Score:** XX/30 (XX%)
**Status:** ✅ Excellent | ⚠️ Needs Work | ❌ Poor
---
## Score Summary
| Category | Score | Status |
|----------|-------|--------|
| Title Tag | X/4 | ✅/⚠️/❌ |
| Meta Description | X/4 | ✅/⚠️/❌ |
| Keyword Placement | X/5 | ✅/⚠️/❌ |
| Content Structure | X/6 | ✅/⚠️/❌ |
| Featured Snippets | X/4 | ✅/⚠️/❌ |
| Internal Linking | X/4 | ✅/⚠️/❌ |
| Technical SEO | X/3 | ✅/⚠️/❌ |
| **Total** | **X/30** | **STATUS** |
---
## Target Keywords
**Primary Keyword:** [e.g., "JavaScript closures"]
**Secondary Keywords:**
- [keyword 1]
- [keyword 2]
- [keyword 3]
**Search Intent:** Informational / How-to / Comparison
---
## Title Tag Analysis
**Current Title:** "[current title from frontmatter]"
**Character Count:** XX characters
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| Length 50-60 chars | ✅/❌ | XX characters |
| Primary keyword in first half | ✅/❌ | [notes] |
| Ends with "in JavaScript" | ✅/❌ | [notes] |
| Contains compelling hook | ✅/❌ | [notes] |
**Issues Found:** [if any]
**Recommended Title:** "[suggested title]" (XX chars)
---
## Meta Description Analysis
**Current Description:** "[current description from frontmatter]"
**Character Count:** XX characters
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| Length 150-160 chars | ✅/❌ | XX characters |
| Starts with action word | ✅/❌ | Starts with "[word]" |
| Contains primary keyword | ✅/❌ | [notes] |
| Promises specific value | ✅/❌ | [notes] |
**Issues Found:** [if any]
**Recommended Description:** "[suggested description]" (XX chars)
---
## Keyword Placement Analysis
**Score:** X/5
| Location | Present | Notes |
|----------|---------|-------|
| Title | ✅/❌ | [notes] |
| Meta description | ✅/❌ | [notes] |
| First 100 words | ✅/❌ | Found at word XX |
| H2 heading | ✅/❌ | Found in: "[H2 text]" |
| Natural reading | ✅/❌ | [no stuffing / stuffing detected] |
**Missing Keyword Placements:**
- [ ] [Location where keyword should be added]
---
## Content Structure Analysis
**Word Count:** X,XXX words
**Score:** X/6
| Check | Status | Notes |
|-------|--------|-------|
| Question hook opening | ✅/❌ | [notes] |
| Code in first 200 words | ✅/❌ | Code appears at word XX |
| "What you'll learn" box | ✅/❌ | [present/missing] |
| Short paragraphs | ✅/❌ | [notes on paragraph length] |
| 1,500+ words | ✅/❌ | X,XXX words |
| Bolded key terms | ✅/❌ | [notes] |
**Structure Issues:**
- [ ] [Issue and recommendation]
---
## Featured Snippet Analysis
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| 40-60 word definition | ✅/❌ | Currently XX words |
| Question-format H2 | ✅/❌ | Found: "[H2]" / Not found |
| Numbered steps | ✅/❌ | [notes] |
| Comparison tables | ✅/❌/N/A | [notes] |
**Snippet Opportunities:**
1. **"What is [concept]" snippet:**
- Current definition: XX words
- Action: [Expand to/Trim to] 40-60 words
2. **"How to [action]" snippet:**
- Action: [Add Steps component / Already present]
---
## Internal Linking Analysis
**Score:** X/4
| Check | Status | Notes |
|-------|--------|-------|
| 3-5 internal links in body | ✅/❌ | Found X links |
| Descriptive anchor text | ✅/❌ | [notes] |
| Prerequisites in Warning | ✅/❌ | [present/missing] |
| Related Concepts section | ✅/❌ | X cards present |
**Current Internal Links:**
1. [Anchor text] → `/concepts/[slug]`
2. [Anchor text] → `/concepts/[slug]`
**Recommended Links to Add:**
- Link to [concept] in [section/context]
- Link to [concept] in [section/context]
**Bad Anchor Text Found:**
- Line XX: "click here" → change to "[descriptive text]"
---
## Technical SEO Analysis
**Score:** X/3
| Check | Status | Notes |
|-------|--------|-------|
| Single H1 per page | ✅/❌ | [Found X H1 tags] |
| URL slug contains keyword | ✅/❌ | Current: `/concepts/[slug]` |
| Not an orphan page | ✅/❌ | Linked from X other pages |
**H1 Tags Found:**
- Line XX: `# [H1 text]` ← Should be the only one
- [List any additional H1s that need to be changed to H2]
**Slug Analysis:**
- Current slug: `[slug].mdx`
- Contains keyword: ✅/❌
- Format correct: ✅/❌ (lowercase, hyphens, no special chars)
**Incoming Links Found:**
1. `/concepts/[other-concept]` → Links to this page in [section]
2. `/concepts/[other-concept]` → Links in Related Concepts
**If orphan page, add links from:**
- [Suggested concept page] in [section]
- [Suggested concept page] in Related Concepts
---
## Priority Fixes
### High Priority (Do First)
1. **[Issue]**
- Current: [what it is now]
- Recommended: [what it should be]
- Impact: [why this matters]
2. **[Issue]**
- Current: [what it is now]
- Recommended: [what it should be]
- Impact: [why this matters]
### Medium Priority
1. **[Issue]**
- Recommendation: [fix]
### Low Priority (Nice to Have)
1. **[Issue]**
- Recommendation: [fix]
---
## Competitive Analysis (Optional)
**Top-Ranking Pages for "[primary keyword]":**
1. **[Competitor 1 - URL]**
- What they do well: [observation]
- Word count: ~X,XXX
2. **[Competitor 2 - URL]**
- What they do well: [observation]
- Word count: ~X,XXX
**Our Advantages:**
- [What we do better]
**Gaps to Fill:**
- [What we're missing that competitors have]
---
## Implementation Checklist
After making fixes, verify:
- [ ] Title is 50-60 characters with keyword and hook
- [ ] Description is 150-160 characters with action word and value
- [ ] Primary keyword in title, description, first 100 words, and H2
- [ ] Opens with question hook
- [ ] Code example in first 200 words
- [ ] "What you'll learn" Info box present
- [ ] Paragraphs are 2-4 sentences
- [ ] 1,500+ words total
- [ ] Key terms bolded on first mention
- [ ] 40-60 word definition for featured snippet
- [ ] At least one question-format H2
- [ ] 3-5 internal links with descriptive anchor text
- [ ] Prerequisites in Warning box (if applicable)
- [ ] Related Concepts section has 4 cards
- [ ] Single H1 per page (title only)
- [ ] URL slug contains primary keyword
- [ ] Page linked from at least one other concept page
- [ ] All fixes implemented and verified
---
## Final Recommendation
**Ready to Publish:** ✅ Yes / ❌ No - [reason]
**Next Review Date:** [When to re-audit, e.g., "3 months" or "after major update"]
| Element | Ideal Length |
|---|---|
| Title | 50-60 characters |
| Meta Description | 150-160 characters |
| Definition paragraph | 40-60 words |
| Length | Assessment |
|---|---|
| <1,000 words | Too thin - add depth |
| 1,000-1,500 | Minimum viable |
| 1,500-2,500 | Good |
| 2,500-4,000 | Excellent |
4,000 | Consider splitting
When auditing a concept page for SEO:
Remember: SEO isn't about gaming search engines — it's about making content easy to find for developers who need it. Every optimization should also improve the reader experience.
Weekly Installs
491
Repository
GitHub Stars
66.3K
First Seen
Jan 20, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
opencode337
gemini-cli335
github-copilot313
codex309
claude-code294
cursor287
Schema标记专家指南:结构化数据实现与SEO优化,提升富媒体搜索结果
26,500 周安装
React前端开发模式实战:组件组合、复合组件与渲染属性模式详解
464 周安装
Mermaid 可视化工具 - 自动生成专业图表,优化文档与演示,兼容 Obsidian/GitHub
465 周安装
OpenAI API 完整指南:GPT-5、GPT-4o、DALL-E 3、Whisper 集成与Node.js/JavaScript开发
465 周安装
客户旅程地图制作指南:5步创建跨职能客户体验地图,提升转化与忠诚度
466 周安装
Next.js 15+ 最佳实践指南:文件约定、RSC边界、异步模式与性能优化
466 周安装
Airflow 2 到 3 迁移指南:代码变更、元数据访问与自动化升级
467 周安装
Async-Await.mdx| Slug too long | Shorten to primary keyword: closures.mdx not understanding-javascript-closures-and-scope.mdx |