Run documentation validation checks for frontmatter, links, and structure compliance
Run validation checks on documentation files for frontmatter, links, and structure compliance. Use before commits to catch critical issues like broken links and missing metadata.
/plugin marketplace add gaurangrshah/gsc-plugins/plugin install docs@gsc-pluginsRun documentation validation checks.
/docs-validate [options]
--quick - Fast validation (frontmatter + obvious issues only)--path <dir> - Validate specific directory (default: $DOCS_ROOT)--fix - Attempt to auto-fix simple issues--report - Generate detailed report to /tmp/docs-validation-YYYY-MM-DD.md--quick)| Category | Severity | Example |
|---|---|---|
| Missing frontmatter | Critical | File has no --- block |
| Broken link | Critical | Link to non-existent file |
| Missing required field | Warning | No created date |
| Orphaned file | Warning | Not referenced in README |
| Missing README | Warning | Subdirectory without README.md |
| Stale content | Info | Not updated in 90+ days |
Quick validation before commit:
/docs-validate --quick
Full validation with report:
/docs-validate --report
Validate specific directory:
/docs-validate --path ~/docs/security
Auto-fix simple issues:
/docs-validate --fix
Console output:
📋 Documentation Validation Report
Checked: 42 files
Issues: 3 critical, 5 warnings, 2 info
❌ Critical Issues:
- security/new-policy.md: Missing frontmatter
- guides/README.md: Broken link to old-guide.md
⚠️ Warnings:
- 5 files not referenced in READMEs
ℹ️ Info:
- Consider adding tags to 2 files
Full report: /tmp/docs-validation-2025-01-15.md
When --fix is used:
| Issue | Auto-Fix Action |
|---|---|
| Missing frontmatter | Add minimal frontmatter template |
| Missing created date | Add today's date |
| Malformed date | Convert to YYYY-MM-DD |
Note: Auto-fix creates backups before modifying files.
If worklog plugin is configured, validation results are logged:
INSERT INTO entries (agent, task_type, title, details, outcome, tags)
VALUES ('hostname', 'validation', 'Docs validation', 'details', 'outcome', 'docs,validation');
| Frequency | Mode | When |
|---|---|---|
| Per commit | --quick | Before git commit |
| Weekly | Full | During review |
| Monthly | Full + --report | First of month |