/docs-build

description: Build static documentation site for deployment. Validates docs first, auto-fixes issues, auto-setup on first run. Outputs production-ready HTML/CSS/JS.

Documentation Build Command

Build production-ready static documentation site for deployment to any static host.

**CRITICAL**: Runs pre-flight validation to catch issues BEFORE building.

Your Task

**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.

Step 1: CRITICAL - Run Pre-Flight Validation

**ALWAYS validate BEFORE building to prevent cryptic webpack errors!**

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

const validator = new DocsValidator({
  docsPath: '.specweave/docs/internal',
  autoFix: true,  // Auto-fix common issues
});

console.log('\n🔍 Running pre-build validation...\n');
const result = await validator.validate();

// Show summary
console.log(DocsValidator.formatResult(result));

// If errors remain after auto-fix, STOP and report
if (!result.valid) {
  console.log('\n❌ Documentation has errors that must be fixed before build.');
  console.log('   Fix the issues above, then try again.\n');
  process.exit(1);
}

console.log('\n✅ Validation passed! Proceeding with build...\n');

Step 2: Ensure Docusaurus is Set Up

# Check if Docusaurus is set up
if [ ! -d ".specweave/cache/docs-site/node_modules" ]; then
  echo "Setting up Docusaurus first..."
  # Run the same setup as view command (see view.md for full setup)
  # After setup, continue to build
fi

If not set up, follow the same setup steps as `/docs:view` (Step 3 in view.md).

Step 3: Run Build

cd .specweave/cache/docs-site && npm run build

Step 3: Report Output

echo ""
echo "📦 Build Complete!"
echo ""
echo "   Output: .specweave/cache/docs-site/build/"
echo ""
echo "   Deploy with:"
echo "   • npx serve .specweave/cache/docs-site/build/"
echo "   • Copy to your static host"
echo ""

Output Structure

.specweave/cache/docs-site/build/
├── index.html              <- Landing page
├── strategy/
├── specs/
├── architecture/
│   └── adr/
├── delivery/
├── operations/
├── governance/
├── assets/
│   ├── css/styles.[hash].css
│   └── js/runtime.[hash].js
└── sitemap.xml

Deployment Options

1. Preview Locally

npx serve .specweave/cache/docs-site/build/

2. Copy to Custom Location

# Copy build to docs folder for GitHub Pages
cp -r .specweave/cache/docs-site/build/* docs/
git add docs/
git commit -m "docs: update documentation site"

3. Netlify/Vercel

# Point your deployment to:
.specweave/cache/docs-site/build/

Build vs Preview

| Aspect | Preview | Build | |--------|---------|-------| | **Purpose** | Development | Production | | **Speed** | Instant | 10-30 seconds | | **Output** | Dev server | Static files | | **Hot Reload** | Yes | No | | **Optimization** | No | Yes (minified) | | **Use Case** | Writing docs | Deployment |

Troubleshooting

Build fails with broken links

# View docs first to find errors
/docs:view
# Fix broken links, then build
/docs:build

Out of memory

NODE_OPTIONS="--max-old-space-size=4096" npm run build

Cache issues

cd .specweave/cache/docs-site && npm run clear && npm run build

Reinstall from scratch

rm -rf .specweave/cache/docs-site
/docs:build

See Also

• `/docs:view` - View docs locally with hot reload
• `/docs:organize` - Organize large folders with themed indexes
• `/docs:health` - Documentation health report