docs-validate

Documentation Validation Command

Validate your documentation for Docusaurus compatibility BEFORE starting the preview server or building.

Why This Matters

Docusaurus compilation errors are often cryptic:

• Unexpected character → unquoted HTML attribute
• Unterminated JSX contents → unclosed tag
• Could not parse expression → bad YAML frontmatter

This validator catches these issues before you see webpack errors.

Usage

# Validate internal docs (default)
/docs:validate

# Validate with auto-fix
/docs:validate --fix

# Validate public docs
/docs:validate public

# Validate specific path
/docs:validate --path .specweave/docs/internal/specs

Your Task

CRITICAL: Run validation BEFORE starting preview or build!

Step 1: Determine Docs Path

# Check which docs to validate
DOCS_TYPE="${1:-internal}"  # internal or public

if [ "$DOCS_TYPE" = "public" ]; then
  DOCS_PATH=".specweave/docs/public"
else
  DOCS_PATH=".specweave/docs/internal"
fi

# Verify path exists
if [ ! -d "$DOCS_PATH" ]; then
  echo "❌ Documentation path not found: $DOCS_PATH"
  exit 1
fi

Step 2: Run Validation

Execute the validation using the DocsValidator:

import { DocsValidator } from '../../../src/utils/docs-validator.js';
import * as path from 'path';

// Get options from command args
const autoFix = process.argv.includes('--fix');
const docsType = process.argv.find(a => a === 'public') ? 'public' : 'internal';
const docsPath = path.resolve(`.specweave/docs/${docsType}`);

// Create validator
const validator = new DocsValidator({
  docsPath,
  autoFix,
});

// Run validation
console.log(`\n📋 Validating ${docsType} documentation...`);
console.log(`   Path: ${docsPath}\n`);

const result = await validator.validate();

// Display formatted result
console.log(DocsValidator.formatResult(result));

// Exit with error code if invalid (for CI integration)
if (!result.valid && !autoFix) {
  console.log('💡 Tip: Run with --fix to auto-repair fixable issues\n');
  process.exit(1);
}