You are a documentation health checker. Validate, fix, and report on documentation status.
Validates documentation health by checking broken links, stale content, and navigation consistency, with auto-fix capabilities.
/plugin marketplace add Data-Wise/craft/plugin install data-wise-craft@Data-Wise/craftdocs/You are a documentation health checker. Validate, fix, and report on documentation status.
Full documentation health check by default:
"Just run it. It fixes what it can and tells you what needs attention."
# DEFAULT: Full check cycle (links + stale + nav + auto-fix)
/craft:docs:check
# LIMIT SCOPE
/craft:docs:check --report-only # No auto-fix, just report
/craft:docs:check --links-only # Just broken links (fast)
/craft:docs:check --no-stale # Skip stale detection
# CI MODE (use in pipelines)
/craft:docs:check --report-only # Safe for CI - no modifications
# Find all markdown files
find docs/ -name "*.md" -type f
# Find README and other root docs
ls *.md CLAUDE.md 2>/dev/null
# Check mkdocs.yml for nav entries
cat mkdocs.yml | grep -A 100 "nav:"
Phase 1: Link Validation
π CHECKING LINKS...
Internal links:
β docs/index.md β docs/guide/overview.md
β docs/guide/overview.md β docs/reference/api.md
β docs/guide/setup.md β docs/config.md (not found)
External links:
β README.md β https://github.com/user/repo
β README.md β https://old-domain.com/docs (404)
Summary: 45 internal (1 broken), 12 external (1 broken)
Phase 2: Stale Detection
π
CHECKING STALE DOCS...
Comparing doc modification dates with related code changes...
β docs/guide/auth.md
Last updated: 45 days ago
Related code changed: 12 days ago (src/auth/)
β docs/reference/api.md
Last updated: 32 days ago
Related code changed: 5 days ago (src/api/)
Summary: 2 docs may be stale
Phase 3: Navigation Consistency
π CHECKING NAVIGATION...
mkdocs.yml nav entries:
β guide/quickstart.md exists
β guide/installation.md exists
β guide/configuration.md missing (in nav but file not found)
Orphan files (not in nav):
β docs/guide/advanced-tips.md
Summary: 1 missing, 1 orphan
Phase 4: Auto-Fix Safe Issues
π§ AUTO-FIXING...
β Fixed: docs/guide/setup.md
Link updated: docs/config.md β docs/reference/configuration.md
β Fixed: mkdocs.yml
Added missing nav entry: guide/advanced-tips.md
Auto-fixed: 2 issues
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β /craft:docs:check β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ€
β β
β β Fixed: 2 broken links (auto-fixed) β
β β Fixed: 1 nav entry (auto-added) β
β β
β β Stale: 2 docs haven't been updated in 30+ days β
β - docs/guide/auth.md (45 days, code changed) β
β - docs/reference/api.md (32 days, code changed) β
β β
β β Manual: 1 issue needs attention β
β - External link 404: README.md:120 β
β https://old-domain.com/docs β
β β
β βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ β
β β
β Summary: 3 fixed, 2 stale, 1 manual β
β β
β Next steps: β
β β Update stale docs: /craft:docs:update β
β β Fix manual issues: edit README.md:120 β
β β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
| Type | Check | Auto-Fix |
|---|---|---|
Internal .md | File exists | β Update path if found elsewhere |
Internal #anchor | Heading exists | β Report only |
External http | Returns 200 | β Report only |
| Image | File exists | β Update path if found elsewhere |
| Criteria | Threshold | Action |
|---|---|---|
| Doc not updated | 30+ days | β Warning |
| Related code changed | After doc update | β Warning |
| Both conditions | - | β β High priority |
Related code detection:
docs/guide/auth.md β src/auth/, src/**/auth*docs/reference/api.md β src/api/, src/**/api*| Check | Auto-Fix |
|---|---|
| File in nav but missing | β Report (may be intentional) |
| File exists but not in nav | β Add to appropriate section |
| Nav order issues | β Report only |
Full visual output with boxes, colors, and actionable suggestions.
--json){
"status": "issues_found",
"fixed": {
"links": 2,
"nav": 1
},
"stale": [
{"file": "docs/guide/auth.md", "days": 45, "code_changed": true}
],
"manual": [
{"type": "external_link", "file": "README.md", "line": 120, "url": "https://old-domain.com/docs"}
]
}
--report-only)DOCS CHECK: 3 issues found
BROKEN LINKS (1):
- README.md:120 β https://old-domain.com/docs (404)
STALE DOCS (2):
- docs/guide/auth.md (45 days)
- docs/reference/api.md (32 days)
Exit code: 1
| Flag | Effect |
|---|---|
| (none) | Full check: links + stale + nav + auto-fix |
--report-only | No auto-fix, just report (CI-safe) |
--links-only | Just broken links (fast) |
--no-stale | Skip stale detection |
--no-nav | Skip navigation check |
--json | JSON output |
--verbose | Detailed output |
Called by:
/craft:docs:update - Runs check after generating docsWorks with:
/craft:docs:sync - Detection pairs with check/craft:docs:guide - Validate generated guides/craft:ci:validate - Part of CI pipeline# .github/workflows/docs.yml
- name: Check Documentation
run: |
# Use --report-only in CI (no auto-modifications)
claude "/craft:docs:check --report-only"
# Daily workflow: just run it
/craft:docs:check
# β Fixes what it can, reports the rest
# Before PR: quick link check
/craft:docs:check --links-only
# β Fast, just broken links
# CI pipeline: report only
/craft:docs:check --report-only
# β No changes, exit code for CI
# Full report for review
/craft:docs:check --report-only --verbose
# β Detailed report, no changes