Review Docs

Review Docs

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

Workflow Overview

This skill performs a 5-step review process:

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

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)

Expectations

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

Step 1: Detect Project Type

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

Detection Indicators

Check for Docus/Nuxt Content:

1. package.json dependencies:

   • "docus" - Docus theme
   • "@nuxt/content" - Nuxt Content module
   • "@nuxtjs/mdc" - MDC support

2. Configuration files:

   • nuxt.config.ts or nuxt.config.js with @nuxt/content module
   • content.config.ts - Content collections configuration

3. Content structure:

   • content/ or docs/content/ directory
   • .navigation.yml files in subdirectories
   • MDC syntax in markdown files (::component-name)

4. Project structure:

   • Numbered directories (1.getting-started/, 2.guide/)
   • Frontmatter with navigation, seo fields

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

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

Step 2: Analyze Documentation Structure

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)

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

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

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)

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)

Step 3: Technical Validation

Adapt validation based on project type detected in Step 1.

For Docus/Nuxt Content Projects (Type A)

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

Validate:

1. Frontmatter structure - Required: title, description. Optional: navigation, seo, links
2. MDC component syntax - All Nuxt UI components MUST have u- prefix (::u-page-hero, :::u-button)
3. Code block labels - All code blocks representing files need descriptive labels (```vue [App.vue], ```ts [config.ts])
4. 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>)
5. Package manager coverage - ::code-group install blocks must cover all package managers the project/ecosystem supports
6. Code preview - Use ::code-preview for visually renderable examples (tables, lists, rendered markdown, etc.)
7. Code group scope - Only group equivalent alternatives (e.g., package managers, framework variants) — don't mix unrelated steps (e.g., install command + config file)
8. File naming - Numbered directories/files, kebab-case, .navigation.yml in each section
9. 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.

For Generic Markdown Projects (Type 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