review-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Docs

文档审查

Comprehensive documentation review, optimized for Docus/Nuxt Content but compatible with any Markdown documentation.

全面的文档审查能力，针对Docus/Nuxt Content优化，同时兼容所有Markdown格式文档。

Workflow Overview

工作流概览

This skill performs a 5-step review process:

Detect Project Type - Identify Docus/Nuxt Content vs generic Markdown
Analyze Structure - Map documentation organization, locales, sections
Technical Validation - Check frontmatter, MDC syntax (if applicable), file naming
Content Quality Review - Evaluate clarity, SEO, structure, i18n
Generate Report - Provide categorized, actionable recommendations

本技能执行5步审查流程：

检测项目类型 - 识别是Docus/Nuxt Content项目还是通用Markdown项目
分析结构 - 梳理文档的组织架构、多语言配置、章节划分
技术校验 - 检查frontmatter、MDC语法（若适用）、文件命名规范
内容质量审查 - 评估清晰度、SEO效果、结构合理性、i18n适配情况
生成报告 - 提供分类整理的可执行改进建议

Priority Levels

优先级划分

Critical - Blocks deployment or causes errors (missing frontmatter, invalid MDC syntax)
Important - Significantly impacts UX/SEO (poor metadata, passive voice, unclear headings)
Nice-to-have - Polish and optimization suggestions (add callouts, improve examples)

严重 - 会阻碍部署或引发错误（缺失frontmatter、无效MDC语法）
重要 - 对用户体验/SEO有显著影响（元数据质量差、被动语态、标题不清晰）
可优化 - 打磨优化类建议（添加提示框、优化示例内容）

Expectations

使用说明

This skill generates a detailed report only. After reviewing, it offers to fix identified issues if requested.

本技能仅会生成详细报告。审查完成后，如果用户提出要求，可提供已识别问题的修复服务。

Step 1: Detect Project Type

步骤1：检测项目类型

Goal: Determine if this is a Docus/Nuxt Content project or generic Markdown documentation.

目标： 判断是Docus/Nuxt Content项目还是通用Markdown文档项目。

Detection Indicators

检测指标

Check for Docus/Nuxt Content:

package.json dependencies:
- ```
"docus"
```
  - Docus theme
- ```
"@nuxt/content"
```
  - Nuxt Content module
- ```
"@nuxtjs/mdc"
```
  - MDC support
Configuration files:
- ```
nuxt.config.ts
```
  or
```
nuxt.config.js
```
  with
```
@nuxt/content
```
  module
- ```
content.config.ts
```
  - Content collections configuration
Content structure:
- ```
content/
```
  or
```
docs/content/
```
  directory
- ```
.navigation.yml
```
  files in subdirectories
- MDC syntax in markdown files (
```
::component-name
```
  )
Project structure:
- Numbered directories (
```
1.getting-started/
```
  ,
```
2.guide/
```
  )
- Frontmatter with
```
navigation
```
  ,
```
seo
```
  fields

Docus/Nuxt Content检测项：

package.json依赖：
- ```
"docus"
```
  - Docus主题
- ```
"@nuxt/content"
```
  - Nuxt Content模块
- ```
"@nuxtjs/mdc"
```
  - MDC支持

配置文件：

引入了

@nuxt/content

模块的

nuxt.config.ts

或

nuxt.config.js

```
content.config.ts
```
- 内容集合配置

内容结构：
- 存在
```
content/
```
  或
```
docs/content/
```
  目录
- 子目录下存在
```
.navigation.yml
```
  文件
- Markdown文件中使用MDC语法（
```
::component-name
```
  ）
项目结构：
- 带编号的目录（
```
1.getting-started/
```
  、
```
2.guide/
```
  ）
- frontmatter包含
```
navigation
```
  、
```
seo
```
  字段

Project Type Classification

项目类型分类

Type A: Docus/Nuxt Content Project

All Docus-specific validations apply
MDC component syntax checks (u- prefix requirement)
Nuxt Content frontmatter structure
Navigation files (.navigation.yml)
Full technical validation

Type B: Generic Markdown Documentation

Basic Markdown validation only
Generic frontmatter (title, description, date, author)
Standard Markdown syntax
Focus on content quality (SEO, clarity, structure)
No Docus-specific technical checks

A类：Docus/Nuxt Content项目

适用所有Docus专属校验规则
MDC组件语法检查（要求带
```
u-
```
前缀）
Nuxt Content frontmatter结构校验
导航文件（.navigation.yml）校验
全量技术校验

B类：通用Markdown文档项目

仅适用基础Markdown校验规则
通用frontmatter校验（标题、描述、日期、作者）
标准Markdown语法校验
重点关注内容质量（SEO、清晰度、结构）
不执行Docus专属技术检查

Detection Output

检测输出

After detection, note in the report:

Project Type: [Docus/Nuxt Content | Generic Markdown]
Validation Mode: [Full (Docus-specific) | Basic (Markdown-only)]

Adapt validation steps based on detected type:

Type A (Docus): Execute all steps with full validation
Type B (Generic): Skip Docus-specific checks, focus on content quality

检测完成后，在报告中注明：

Project Type: [Docus/Nuxt Content | Generic Markdown]
Validation Mode: [Full (Docus-specific) | Basic (Markdown-only)]

根据检测到的项目类型调整校验步骤：

A类（Docus）： 执行全量校验的所有步骤
B类（通用）： 跳过Docus专属检查，重点关注内容质量

Step 2: Analyze Documentation Structure

步骤2：分析文档结构

Locate Content Directory

定位内容目录

Find the documentation content directory:

Check for
```
docs/content/
```
(most common)
Check for
```
content/
```
(root-level)
Check for
```
app/content/
```
(alternative location)

查找文档内容目录：

优先检查
```
docs/content/
```
（最常见）
再检查根目录下的
```
content/
```
最后检查
```
app/content/
```
（替代路径）

Detect Locales

检测多语言配置

Identify language structure by examining subdirectories:

Single language (no locale subdirectories):

content/
├── index.md
├── 1.getting-started/
└── 2.guide/

Multi-language (locale subdirectories):

content/
├── en/
│   ├── index.md
│   ├── 1.getting-started/
│   └── 2.guide/
└── fr/
    ├── index.md
    ├── 1.getting-started/
    └── 2.guide/

Detection logic:

If immediate subdirectories are 2-letter codes (en, fr, es, de, etc.), it's multi-language
If immediate subdirectories are numbered (1.getting-started), it's single language

通过子目录结构识别多语言配置：

单语言（无locale子目录）：

content/
├── index.md
├── 1.getting-started/
└── 2.guide/

多语言（带locale子目录）：

content/
├── en/
│   ├── index.md
│   ├── 1.getting-started/
│   └── 2.guide/
└── fr/
    ├── index.md
    ├── 1.getting-started/
    └── 2.guide/

检测逻辑：

如果一级子目录是2位语言代码（en、fr、es、de等），则为多语言项目
如果一级子目录是带编号的目录（1.getting-started），则为单语言项目

List Documentation Sections

列出文档章节

Identify all numbered directories within each locale:

```
1.getting-started/
```
```
2.guide/
```
or
```
2.concepts/
```
```
3.api/
```
or
```
3.essentials/
```
```
4.advanced/
```
or
```
4.ai/
```

For each section, note:

Section name
Presence of
```
.navigation.yml
```
file
Number of pages (count
```
.md
```
files)
Page file names

识别每个locale下的所有带编号目录：

```
1.getting-started/
```
```
2.guide/
```
或
```
2.concepts/
```
```
3.api/
```
或
```
3.essentials/
```
```
4.advanced/
```
或
```
4.ai/
```

对每个章节，记录：

章节名称
是否存在
```
.navigation.yml
```
文件
页面数量（统计
```
.md
```
文件数）
页面文件名

Verify Core Files

校验核心文件

Check for required files:

```
index.md
```
exists at root of each locale
```
.navigation.yml
```
in each section directory
Numbered files follow pattern (
```
1.introduction.md
```
,
```
2.installation.md
```
)

检查必填文件是否存在：

每个locale根目录下存在
```
index.md
```
每个章节目录下存在
```
.navigation.yml
```
带编号的文件符合命名规范（
```
1.introduction.md
```
、
```
2.installation.md
```
）

Create Structure Map

生成结构映射

Document the structure for the report:

Project: [project-name]
Locales: [en, fr] (or "Single language")
Sections:
  - 1.getting-started: 5 pages, .navigation.yml ✅
  - 2.guide: 8 pages, .navigation.yml ✅
  - 3.api: 3 pages, .navigation.yml ❌ (missing)

在报告中记录文档结构：

Project: [project-name]
Locales: [en, fr]（或"Single language"）
Sections:
  - 1.getting-started: 5 pages, .navigation.yml ✅
  - 2.guide: 8 pages, .navigation.yml ✅
  - 3.api: 3 pages, .navigation.yml ❌ (missing)

Step 3: Technical Validation

步骤3：技术校验

Adapt validation based on project type detected in Step 1.

根据步骤1检测到的项目类型调整校验规则。

For Docus/Nuxt Content Projects (Type A)

针对Docus/Nuxt Content项目（A类）

Perform full technical validation using references/technical-checks.md:

Validate:

Frontmatter structure - Required:
```
title
```
,
```
description
```
. Optional:
```
navigation
```
,
```
seo
```
,
```
links
```
MDC component syntax - All Nuxt UI components MUST have
```
u-
```
prefix (
```
::u-page-hero
```
,
```
:::u-button
```
)
Code block labels - All code blocks representing files need descriptive labels (
```
```vue [App.vue]
```
,
```
```ts [config.ts]
```
)
Code language consistency - Code examples should match the project's language stack (e.g., TypeScript if the project uses TypeScript,
```
lang="ts"
```
on Vue
```
<script setup>
```
)
Package manager coverage -
```
::code-group
```
install blocks must cover all package managers the project/ecosystem supports
Code preview - Use
```
::code-preview
```
for visually renderable examples (tables, lists, rendered markdown, etc.)
Code group scope - Only group equivalent alternatives (e.g., package managers, framework variants) — don't mix unrelated steps (e.g., install command + config file)
File naming - Numbered directories/files, kebab-case,
```
.navigation.yml
```
in each section
Hidden pages - Use
```
navigation: false
```
for pages that should exist as routes but not appear in sidebar

Common Critical Errors:

Missing
```
u-
```
prefix:
```
::page-hero
```
→ should be
```
::u-page-hero
```
Missing required frontmatter:
```
title
```
,
```
description
```
Invalid
```
.navigation.yml
```
structure
Missing section
```
index.md
```
causing 404 on section root URL

See references/technical-checks.md for complete validation rules, examples, and error patterns.

参考references/technical-checks.md执行全量技术校验：

校验项：

frontmatter结构 - 必填项：
```
title
```
、
```
description
```
。可选项：
```
navigation
```
、
```
seo
```
、
```
links
```
MDC组件语法 - 所有Nuxt UI组件必须带
```
u-
```
前缀（
```
::u-page-hero
```
、
```
:::u-button
```
）
代码块标签 - 所有代表文件的代码块需要带描述性标签（
```
```vue [App.vue]
```
、
```
```ts [config.ts]
```
）
代码语言一致性 - 代码示例需要匹配项目的技术栈（例如如果项目使用TypeScript，Vue的
```
<script setup>
```
要加
```
lang="ts"
```
）
包管理器覆盖 -
```
::code-group
```
安装块需要覆盖项目/生态支持的所有包管理器
代码预览 - 可可视化渲染的示例（表格、列表、渲染后的Markdown等）要使用
```
::code-preview
```
代码组范围 - 仅对等替代内容分组（例如包管理器、框架变体）——不要把不相关的步骤混在一起（例如安装命令+配置文件）
文件命名 - 目录/文件带编号、使用kebab-case格式、每个章节下有
```
.navigation.yml
```
隐藏页面 - 需要作为路由存在但不显示在侧边栏的页面要加
```
navigation: false
```
配置

常见严重错误：

缺失
```
u-
```
前缀：
```
::page-hero
```
→ 应为
```
::u-page-hero
```
缺失必填frontmatter：
```
title
```
、
```
description
```
无效的
```
.navigation.yml
```
结构
缺失章节
```
index.md
```
导致章节根路径404

参考references/technical-checks.md查看完整校验规则、示例和错误模式。

For Generic Markdown Projects (Type B)

针对通用Markdown项目（B类）

Simplified validation - Skip Docus-specific checks:

Basic Frontmatter Validation:

Check for common fields:
```
title
```
,
```
description
```
,
```
date
```
,
```
author
```
,
```
tags
```
No strict requirements - just recommendations
Flag if completely missing frontmatter

Standard Markdown Syntax:

Validate basic markdown (headings, lists, links, code blocks)
Check for broken internal links
Verify image paths exist

Skip:

MDC component syntax (not applicable)
Nuxt Content frontmatter structure
```
.navigation.yml
```
files
Docus-specific conventions

Focus on:

Content quality (next step)
SEO optimization
Clarity and readability
General structure

简化校验 - 跳过Docus专属检查：

基础frontmatter校验：

检查通用字段：
```
title
```
、
```
description
```
、
```
date
```
、
```
author
```
、
```
tags
```
无强制要求，仅提供建议
如果完全缺失frontmatter需标记

标准Markdown语法校验：

校验基础Markdown语法（标题、列表、链接、代码块）
检查失效的内部链接
验证图片路径是否存在

跳过项：

MDC组件语法（不适用）
Nuxt Content frontmatter结构
```
.navigation.yml
```
文件校验
Docus专属规范

重点关注：

内容质量（下一步）
SEO优化
清晰度和可读性
整体结构

Step 4: Content Quality Review

步骤4：内容质量审查

This step applies to ALL project types (both Docus and generic Markdown).

Evaluate content quality across four dimensions. Refer to reference files for detailed checklists.

本步骤适用于所有项目类型（Docus和通用Markdown都适用）。

从四个维度评估内容质量，参考对应的参考文件获取详细检查清单。

Clarity Review

清晰度审查

Use references/clarity-checks.md to check:

Voice & Tone: Active voice, present tense, second person
Sentence Structure: 15-20 words target, avoid wordy phrases
Paragraph Structure: 2-5 sentences, 200-400 words between headings
Action-Based Headings: Page titles (H1) and headings (H2/H3) use action verbs for guides (Nuxt pattern)
- Examples: "Create Your First Module", "Configure your app", "Build a Plugin"
- Exceptions: Getting Started (nouns), API (function names), Concepts (descriptive)
Terminology: Consistent naming, technical terms defined
Code Examples: Complete, copy-pasteable, realistic, with file labels

参考references/clarity-checks.md检查：

语气语态： 主动语态、现在时、第二人称
句子结构： 目标长度15-20词，避免冗余表述
段落结构： 每段2-5句，两个标题之间的内容控制在200-400词
行动导向标题： 指南类页面的页面标题（H1）和二级/三级标题使用动作动词（Nuxt规范）
- 示例："Create Your First Module"、"Configure your app"、"Build a Plugin"
- 例外：入门类（名词）、API文档（函数名）、概念类（描述性）
术语规范： 命名统一，技术术语有定义
代码示例： 完整、可直接复制、符合真实场景、带文件标签

SEO Review

SEO审查

Use references/seo-checks.md to check:

Titles: 50-60 chars, keywords, unique
Descriptions: 120-160 chars, compelling, unique
Headings: Single H1, logical hierarchy (H1→H2→H3), descriptive
URLs: Kebab-case, descriptive, stable
Links: Descriptive anchors, "Next steps" sections
Content Length: 300+ words for landing, 400+ for guides, 200-400 per section
Images: Alt text, color mode variants

参考references/seo-checks.md检查：

标题： 50-60字符、包含关键词、唯一
描述： 120-160字符、有吸引力、唯一
标题层级： 单个H1、逻辑层级清晰（H1→H2→H3）、描述准确
URL： kebab-case格式、描述清晰、稳定
链接： 锚文本描述清晰、包含"下一步"板块
内容长度： 落地页300词以上、指南类400词以上、每个章节200-400词
图片： 有替代文本、适配深浅色模式

Structure Review

结构审查

Use references/structure-checks.md to check:

Hierarchy: Max 3 levels, logical progression
Organization: 2-15 pages per section,
```
.navigation.yml
```
present, appropriate icons
Flow: Logical progression, "Next Steps" links, no orphaned pages
Landing Page: Hero, features, quick start
Consistency: Similar structure across pages

参考references/structure-checks.md检查：

层级： 最多3级标题、逻辑递进合理
组织： 每个章节2-15个页面、存在
```
.navigation.yml
```
、图标适配
流程： 逻辑递进、有"下一步"链接、无孤立页面
落地页： 包含首屏块、功能特性、快速入门
一致性： 不同页面结构统一

i18n Review (if multi-language)

i18n审查（多语言项目适用）

Use references/i18n-checks.md to check:

Parallel Structure: Same directories, files, page counts across locales
Translation Completeness: Similar content length (±30%), same headings
Navigation: Same icons, translated titles
Locale-Specific: No mixed languages, correct internal links, translated comments

参考references/i18n-checks.md检查：

结构对齐： 不同locale下的目录、文件、页面数量一致
翻译完整性： 内容长度接近（±30%）、标题一致
导航： 图标一致、标题已翻译
locale适配： 无语言混杂、内部链接正确、注释已翻译

Step 5: Generate Report

步骤5：生成报告

Create a comprehensive review report using assets/report-template.md.

Adapt report based on project type:

Docus/Nuxt Content: Include all sections (Technical, SEO, Clarity, Structure, i18n)
Generic Markdown: Focus on content quality (SEO, Clarity, Structure), omit Docus-specific technical issues

参考assets/report-template.md生成完整的审查报告。

根据项目类型调整报告：

Docus/Nuxt Content： 包含所有板块（技术、SEO、清晰度、结构、i18n）
通用Markdown： 重点关注内容质量（SEO、清晰度、结构），省略Docus专属技术问题

Report Structure

报告结构

markdown

undefined

markdown

undefined

Documentation Review Report

文档审查报告

Generated: [current date and time] Project: [project name from package.json or directory] Reviewed: [X] pages across [Y] sections in [locales]

生成时间： [当前日期和时间] 项目： [从package.json或目录名获取的项目名称] 审查范围： [X]个页面，覆盖[Y]个章节，[语言列表]

Executive Summary

执行摘要

Critical Issues: [count] (must fix - block deployment/cause errors)
Important Issues: [count] (significant impact on UX/SEO)
Nice-to-Have: [count] (polish and optimization recommendations)

Overall Assessment: [1-2 sentence summary of documentation quality]

严重问题： [数量]（必须修复 - 会阻碍部署/引发错误）
重要问题： [数量]（对UX/SEO有显著影响）
可优化建议： [数量]（打磨优化类建议）

整体评估： [1-2句话总结文档质量]

Critical Issues

严重问题

[List all Critical issues grouped by category]

[按类别列出所有严重问题]

Technical: MDC Syntax Errors

技术：MDC语法错误

Missing u- prefix on Nuxt UI components

Nuxt UI组件缺失u-前缀

File:

/content/en/1.getting-started/1.introduction.md:15

Problem: Page hero component missing

u-

prefix

Current: ```markdown ::page-hero #title Welcome :: ```

Should Be: ```markdown ::u-page-hero #title Welcome :: ```

Impact: Component will not render, causing build errors

文件：

/content/en/1.getting-started/1.introduction.md:15

问题： 页面首屏组件缺失

u-

前缀

当前代码： ```markdown ::page-hero #title Welcome :: ```

正确代码： ```markdown ::u-page-hero #title Welcome :: ```

影响： 组件无法渲染，导致构建错误

Technical: Missing Frontmatter

技术：缺失frontmatter

[Similar format for each issue]

[每个问题使用相同格式]

Important Issues

重要问题

[List all Important issues grouped by category: SEO, Clarity, Structure]

[按类别列出所有重要问题：SEO、清晰度、结构]

SEO: Suboptimal Metadata

SEO：元数据不达标

[Details with file paths and recommendations]

[包含文件路径和建议的详细说明]

Clarity: Passive Voice

清晰度：被动语态使用

[Details with examples and suggested rewrites]

[包含示例和改写建议的详细说明]

Structure: Poor Navigation

结构：导航体验差

[Details with organizational recommendations]

[包含组织架构优化建议的详细说明]

Nice-to-Have Suggestions

可优化建议

[List optimization suggestions by category]

[按类别列出优化建议]

SEO Optimizations

SEO优化

[File]: [Suggestion]

[文件]：[建议内容]

Clarity Improvements

清晰度提升

[File]: Consider adding
```
::tip
```
callout for [specific content]

[文件]：建议为[特定内容]添加
```
::tip
```
提示框

Structure Enhancements

结构优化

[Section]: Consider splitting into subsections

[章节]：建议拆分为多个子章节

Locale-Specific Issues

多语言专属问题

[Only if multi-language detected]

[仅检测到多语言配置时展示]

French (

/fr/

)

法语（

/fr/

）

[Translation issues]

[翻译问题]

Statistics

统计数据

Content Overview

内容概览

Section	Pages (en)	Pages (fr)	Avg Words/Page
Getting Started	[X]	[X]	~[XXX]
Guide	[X]	[X]	~[XXX]

章节	页面数（英文）	页面数（法语）	平均单页字数
入门指南	[X]	[X]	~[XXX]
开发指南	[X]	[X]	~[XXX]

Issue Breakdown

问题分布

Category	Critical	Important	Nice-to-Have	Total
Technical	[X]	[X]	[X]	[X]
SEO	[X]	[X]	[X]	[X]
Clarity	[X]	[X]	[X]	[X]
Structure	[X]	[X]	[X]	[X]
i18n	[X]	[X]	[X]	[X]
Total	[X]	[X]	[X]	[X]

类别	严重	重要	可优化	总计
技术	[X]	[X]	[X]	[X]
SEO	[X]	[X]	[X]	[X]
清晰度	[X]	[X]	[X]	[X]
结构	[X]	[X]	[X]	[X]
i18n	[X]	[X]	[X]	[X]
总计	[X]	[X]	[X]	[X]

Positive Highlights

亮点

[Call out 2-3 things done well]

Good use of callouts and code examples
Consistent MDC component usage
Well-organized section structure

[列出2-3个做的好的地方]

提示框和代码示例使用规范
MDC组件使用统一
章节结构清晰有序

Recommended Action Plan

建议行动方案

Priority 1: Fix Critical Issues (Today)

优先级1：修复严重问题（今日）

[Specific actionable items]

Estimated fixes: [X] files

[具体可执行项]

预计修改文件数： [X]

Priority 2: Important Issues (This Week)

优先级2：修复重要问题（本周）

[Specific actionable items]

Estimated fixes: [X] files

[具体可执行项]

预计修改文件数： [X]

Priority 3: Nice-to-Have (Next Sprint)

优先级3：优化项（下个迭代）

[Specific actionable items]

Estimated fixes: [X] files

[具体可执行项]

预计修改文件数： [X]

Next Steps

下一步

Would you like me to:

Fix all Critical issues - I can automatically correct MDC syntax and frontmatter issues
Rewrite specific sections - Point out which pages need clarity improvements, and I'll rewrite them
Optimize SEO metadata - I can update all titles and descriptions to optimal lengths
Restructure content - If sections need reorganization, I can help restructure
Complete translations - If you need i18n content completed

Or specify what you'd like to focus on first.

undefined

你希望我执行以下哪项操作：

修复所有严重问题 - 我可以自动修正MDC语法和frontmatter问题
重写指定章节 - 告知需要提升清晰度的页面，我会进行重写
优化SEO元数据 - 我可以将所有标题和描述更新到最优长度
重构内容结构 - 如果章节需要重新组织，我可以提供重构支持
完成翻译内容 - 如果你需要补全i18n内容

也可以说明你希望优先处理的内容。

undefined

Report Generation Guidelines

报告生成规范

Be specific:

Include exact file paths and line numbers
Show current vs. recommended code
Explain why each issue matters (impact)

Be actionable:

Provide clear fix instructions
Include code examples
Prioritize by impact

Be balanced:

Highlight positive aspects
Don't overwhelm with minor issues
Focus on high-impact improvements

After generating the report:

Offer to fix issues if the user requests
Be ready to address specific categories or files
Suggest starting with Critical issues

内容具体：

包含准确的文件路径和行号
展示当前代码和建议代码
说明每个问题的影响

可执行：

提供清晰的修复指导
包含代码示例
按影响优先级排序

客观平衡：

突出做的好的部分
不要堆砌小问题
重点关注高影响的改进

生成报告后：

如果用户要求，主动提供问题修复服务
随时响应特定类别或文件的处理需求
建议优先处理严重问题

Quick Reference

快速参考

Most Common Issues:

Missing
```
u-
```
prefix on Nuxt UI components (
```
::page-hero
```
→
```
::u-page-hero
```
)
SEO descriptions too short (need 120-160 chars)
Passive voice in instructions ("can be done" → "do it")
Generic headings ("Configuration" → "Configure your app")
Code blocks missing file name labels (every block representing a file should have one)
Code language not matching the project's stack (e.g., missing
```
lang="ts"
```
on Vue
```
<script setup>
```
in a TypeScript project)
Incomplete package manager coverage in
```
::code-group
```
install blocks (check against the ecosystem/project)
Unrelated steps grouped in
```
::code-group
```
(e.g., install command + config file) — keep as separate blocks
Missing
```
::code-preview
```
where rendered preview would add clarity (tables, lists, etc.)
Section landing page missing → 404 on section root URL (add
```
index.md
```
with
```
navigation: false
```
if needed)

See reference files for complete checklists and examples.

最常见问题：

Nuxt UI组件缺失
```
u-
```
前缀（
```
::page-hero
```
→
```
::u-page-hero
```
）
SEO描述过短（需要120-160字符）
说明内容使用被动语态（"can be done" → "do it"）
标题过于通用（"Configuration" → "Configure your app"）
代码块缺失文件名标签（所有代表文件的代码块都需要加标签）
代码语言不匹配项目技术栈（例如TypeScript项目的Vue
```
<script setup>
```
缺失
```
lang="ts"
```
）
```
::code-group
```
安装块没有覆盖所有支持的包管理器（参考项目/生态要求）
不相关步骤被放在同一个
```
::code-group
```
里（例如安装命令+配置文件）——拆分为独立代码块
应该添加渲染预览的场景缺失
```
::code-preview
```
（表格、列表等）
缺失章节落地页 → 章节根路径404（需要时添加
```
index.md
```
并配置
```
navigation: false
```
）

参考文件获取完整检查清单和示例。