From docus
Review documentation for quality, clarity, SEO, and technical correctness. Optimized for Docus/Nuxt Content but works with any Markdown documentation. Use when asked to: "review docs", "check documentation", "audit docs", "validate documentation", "improve docs quality", "analyze documentation", "check my docs", "review my documentation pages", "validate MDC syntax", "check for SEO issues", "analyze doc structure". Provides actionable recommendations categorized by priority (Critical, Important, Nice-to-have).
npx claudepluginhub pleaseai/claude-code-plugins --plugin docusThis skill uses the workspace's default tool permissions.
Comprehensive documentation review, optimized for Docus/Nuxt Content but compatible with any Markdown documentation.
Assesses documentation quality across readability, consistency, audience fit, and prose clarity. Produces scored reviews with actionable findings before releases or doc reviews.
Audits documentation staleness via git history and maintains quality with auto-fixes. Maps code paths to docs in $JAAN_DOCS_DIR. Use for reviewing or updating docs.
Validates documentation quality for research software using Vale prose linting, HTMLProofer link checking, markdownlint Markdown validation, code example testing, container instructions, and CI integration.
Share bugs, ideas, or general feedback.
Comprehensive documentation review, optimized for Docus/Nuxt Content but compatible with any Markdown documentation.
This skill performs a 5-step review process:
This skill generates a detailed report only. After reviewing, it offers to fix identified issues if requested.
Goal: Determine if this is a Docus/Nuxt Content project or generic Markdown documentation.
Check for Docus/Nuxt Content:
package.json dependencies:
"docus" - Docus theme"@nuxt/content" - Nuxt Content module"@nuxtjs/mdc" - MDC supportConfiguration files:
nuxt.config.ts or nuxt.config.js with @nuxt/content modulecontent.config.ts - Content collections configurationContent structure:
content/ or docs/content/ directory.navigation.yml files in subdirectories::component-name)Project structure:
1.getting-started/, 2.guide/)navigation, seo fieldsType A: Docus/Nuxt Content Project
Type B: Generic Markdown Documentation
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:
Find the documentation content directory:
docs/content/ (most common)content/ (root-level)app/content/ (alternative location)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:
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:
.navigation.yml file.md files)Check for required files:
index.md exists at root of each locale.navigation.yml in each section directory1.introduction.md, 2.installation.md)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)
Adapt validation based on project type detected in Step 1.
Perform full technical validation using references/technical-checks.md:
Validate:
title, description. Optional: navigation, seo, linksu- prefix (::u-page-hero, :::u-button)```vue [App.vue], ```ts [config.ts])lang="ts" on Vue <script setup>)::code-group install blocks must cover all package managers the project/ecosystem supports::code-preview for visually renderable examples (tables, lists, rendered markdown, etc.).navigation.yml in each sectionnavigation: false for pages that should exist as routes but not appear in sidebarCommon Critical Errors:
u- prefix: ::page-hero → should be ::u-page-herotitle, description.navigation.yml structureindex.md causing 404 on section root URLSee references/technical-checks.md for complete validation rules, examples, and error patterns.
Simplified validation - Skip Docus-specific checks:
Basic Frontmatter Validation:
title, description, date, author, tagsStandard Markdown Syntax:
Skip:
.navigation.yml filesFocus on:
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.
Use references/clarity-checks.md to check:
Use references/seo-checks.md to check:
Use references/structure-checks.md to check:
.navigation.yml present, appropriate iconsUse references/i18n-checks.md to check:
Create a comprehensive review report using assets/report-template.md.
Adapt report based on project type:
# Documentation Review Report
**Generated:** [current date and time]
**Project:** [project name from package.json or directory]
**Reviewed:** [X] pages across [Y] sections in [locales]
---
## 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]
---
## Critical Issues
[List all Critical issues grouped by category]
### Technical: MDC Syntax Errors
#### Missing u- prefix on Nuxt UI components
**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
---
### Technical: Missing Frontmatter
[Similar format for each issue]
---
## Important Issues
[List all Important issues grouped by category: SEO, Clarity, Structure]
### SEO: Suboptimal Metadata
[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
- **[File]**: [Suggestion]
### Clarity Improvements
- **[File]**: Consider adding `::tip` callout for [specific content]
### Structure Enhancements
- **[Section]**: Consider splitting into subsections
---
## Locale-Specific Issues
[Only if multi-language detected]
### French (`/fr/`)
- [Translation issues]
---
## Statistics
### Content Overview
| Section | Pages (en) | Pages (fr) | Avg Words/Page |
|---------|------------|------------|----------------|
| Getting Started | [X] | [X] | ~[XXX] |
| Guide | [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]** |
---
## Positive Highlights
[Call out 2-3 things done well]
- Good use of callouts and code examples
- Consistent MDC component usage
- Well-organized section structure
---
## Recommended Action Plan
### Priority 1: Fix Critical Issues (Today)
1. [Specific actionable items]
**Estimated fixes:** [X] files
### Priority 2: Important Issues (This Week)
1. [Specific actionable items]
**Estimated fixes:** [X] files
### Priority 3: Nice-to-Have (Next Sprint)
1. [Specific actionable items]
**Estimated fixes:** [X] files
---
## Next Steps
**Would you like me to:**
1. **Fix all Critical issues** - I can automatically correct MDC syntax and frontmatter issues
2. **Rewrite specific sections** - Point out which pages need clarity improvements, and I'll rewrite them
3. **Optimize SEO metadata** - I can update all titles and descriptions to optimal lengths
4. **Restructure content** - If sections need reorganization, I can help restructure
5. **Complete translations** - If you need i18n content completed
**Or specify what you'd like to focus on first.**
Be specific:
Be actionable:
Be balanced:
After generating the report:
Most Common Issues:
u- prefix on Nuxt UI components (::page-hero → ::u-page-hero)lang="ts" on Vue <script setup> in a TypeScript project)::code-group install blocks (check against the ecosystem/project)::code-group (e.g., install command + config file) — keep as separate blocks::code-preview where rendered preview would add clarity (tables, lists, etc.)index.md with navigation: false if needed)See reference files for complete checklists and examples.