---
name: specweave-docs-preview:build
description: Build static documentation site for deployment. Generates production-ready HTML/CSS/JS files optimized for static hosting.
---

# Documentation Build Command

Build a production-ready static documentation site from your SpecWeave living documentation.

## Your Task

Execute the following workflow to build the static documentation site:

### Step 1: Load the Build Utilities

```typescript
import { buildStaticSite, isSetupNeeded } from '../../../src/utils/docs-preview/index.js';
import * as fs from 'fs-extra';
import * as path from 'path';
```

### Step 2: Check Prerequisites

```typescript
const projectRoot = process.cwd();

// Check if docs preview is configured
const configPath = path.join(projectRoot, '.specweave', 'config.json');
let config: any = {};
if (fs.existsSync(configPath)) {
  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
}

const docsConfig = config.documentation?.preview || {};

console.log('\n📦 Building Documentation Site...\n');

// Check if Docusaurus is installed
const setupNeeded = await isSetupNeeded(projectRoot);

if (setupNeeded) {
  console.error('❌ Docusaurus not installed\n');
  console.log('💡 Solution:');
  console.log('   Run: /specweave-docs-preview:preview');
  console.log('   This will install Docusaurus first\n');
  process.exit(1);
}
```

### Step 3: Build the Static Site

```typescript
try {
  console.log('ℹ️  Building production site...');
  console.log('   • Compiling React components');
  console.log('   • Optimizing assets');
  console.log('   • Generating static HTML\n');

  await buildStaticSite(projectRoot);

  const buildPath = path.join(projectRoot, '.specweave', 'docs-site-internal', 'build');
  const buildStats = await getBuildStats(buildPath);

  console.log('\n✅ Build Complete!\n');
  console.log('📊 Build Statistics:');
  console.log(`   • Pages: ${buildStats.pages} HTML files`);
  console.log(`   • Size: ${buildStats.totalSize}`);
  console.log(`   • Location: ${buildPath}\n`);

  console.log('🚀 Deployment Options:\n');
  console.log('1️⃣  Netlify:');
  console.log('   cd .specweave/docs-site-internal');
  console.log('   npx netlify deploy --dir=build --prod\n');

  console.log('2️⃣  Vercel:');
  console.log('   cd .specweave/docs-site-internal');
  console.log('   npx vercel --prod\n');

  console.log('3️⃣  GitHub Pages:');
  console.log('   cp -r build/* docs/');
  console.log('   git add docs/ && git commit -m "docs: update"');
  console.log('   git push\n');

  console.log('4️⃣  Static Server (local test):');
  console.log('   npx serve build/\n');

  console.log('5️⃣  Your own server:');
  console.log('   scp -r build/* user@server:/var/www/docs/\n');

} catch (error: any) {
  console.error('\n❌ Build Failed\n');
  console.error(`Error: ${error.message}\n`);

  console.log('💡 Troubleshooting:');
  console.log('   • Check all markdown files have valid frontmatter');
  console.log('   • Ensure no broken internal links');
  console.log('   • Run preview first to catch errors: /specweave-docs-preview:preview');
  console.log('   • Check build logs above for specific errors\n');

  process.exit(1);
}
```

### Step 4: Helper Function - Get Build Statistics

```typescript
async function getBuildStats(buildPath: string): Promise<{
  pages: number;
  totalSize: string;
}> {
  let pages = 0;
  let totalBytes = 0;

  async function walk(dir: string) {
    const files = await fs.readdir(dir);
    for (const file of files) {
      const filePath = path.join(dir, file);
      const stats = await fs.stat(filePath);
      if (stats.isDirectory()) {
        await walk(filePath);
      } else {
        totalBytes += stats.size;
        if (file.endsWith('.html')) {
          pages++;
        }
      }
    }
  }

  await walk(buildPath);

  const totalMB = (totalBytes / 1024 / 1024).toFixed(2);
  return {
    pages,
    totalSize: `${totalMB} MB`
  };
}
```

## What Gets Built

### Output Directory Structure
```
.specweave/docs-site-internal/build/
├── index.html                    ← Landing page
├── docs/
│   ├── strategy/
│   │   ├── prd-001/
│   │   │   └── index.html
│   │   └── okrs/
│   │       └── index.html
│   ├── specs/
│   │   ├── spec-001-auth/
│   │   │   └── index.html
│   │   └── spec-002-payments/
│   │       └── index.html
│   └── architecture/
│       ├── hld-system/
│       │   └── index.html
│       └── adr/
│           └── 0001-database-choice/
│               └── index.html
├── assets/
│   ├── css/
│   │   └── styles.[hash].css    ← Optimized CSS
│   ├── js/
│   │   └── runtime.[hash].js    ← React runtime
│   └── images/                  ← Optimized images
└── sitemap.xml                  ← Search engine sitemap
```

### Build Optimizations
1. **Code Splitting**: React chunks loaded on demand
2. **Asset Optimization**: CSS/JS minified and compressed
3. **Image Optimization**: Auto-resized and compressed
4. **Static HTML**: Pre-rendered pages for fast loading
5. **Search Index**: Pre-generated search index
6. **Sitemap**: Auto-generated for SEO

## Deployment Examples

### Netlify (Recommended)

**Option 1: CLI**
```bash
cd .specweave/docs-site-internal
npx netlify deploy --dir=build --prod
```

**Option 2: Drag & Drop**
1. Go to https://app.netlify.com/drop
2. Drag `.specweave/docs-site-internal/build/` folder
3. Done! Get instant URL

**Option 3: Git Integration**
1. Create `netlify.toml`:
   ```toml
   [build]
     base = ".specweave/docs-site-internal"
     publish = "build"
     command = "npm run build"
   ```
2. Connect GitHub repo
3. Auto-deploy on push

### Vercel

```bash
cd .specweave/docs-site-internal
npx vercel --prod
```

### GitHub Pages

**Option 1: docs/ folder**
```bash
# 1. Copy build to docs/
cp -r .specweave/docs-site-internal/build/* docs/

# 2. Enable GitHub Pages
# Go to Settings → Pages → Source: main branch /docs folder

# 3. Push
git add docs/
git commit -m "docs: update documentation site"
git push
```

**Option 2: gh-pages branch**
```bash
# 1. Install gh-pages
npm install -g gh-pages

# 2. Deploy
gh-pages -d .specweave/docs-site-internal/build
```

### AWS S3 + CloudFront

```bash
# 1. Sync to S3
aws s3 sync .specweave/docs-site-internal/build/ s3://your-bucket/ \
  --delete \
  --cache-control "max-age=31536000,public"

# 2. Invalidate CloudFront
aws cloudfront create-invalidation \
  --distribution-id YOUR_DIST_ID \
  --paths "/*"
```

### Docker + Nginx

**Dockerfile:**
```dockerfile
FROM nginx:alpine
COPY .specweave/docs-site-internal/build/ /usr/share/nginx/html/
EXPOSE 80
```

**Build and run:**
```bash
docker build -t docs .
docker run -p 80:80 docs
```

### Your Own Server

**Nginx config:**
```nginx
server {
    listen 80;
    server_name docs.example.com;
    root /var/www/docs;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}
```

**Deploy:**
```bash
scp -r .specweave/docs-site-internal/build/* user@server:/var/www/docs/
```

## Testing Before Deployment

### Local Testing with Serve

```bash
# 1. Install serve
npm install -g serve

# 2. Serve build folder
cd .specweave/docs-site-internal
serve build/

# 3. Open browser
# Visit: http://localhost:3000
```

### Check Lighthouse Scores

```bash
# 1. Install lighthouse
npm install -g lighthouse

# 2. Run audit
lighthouse http://localhost:3000 \
  --view \
  --output html

# Expected scores:
# Performance: 100
# Accessibility: 100
# Best Practices: 100
# SEO: 100
```

## Expected Output

**Successful Build:**
```
📦 Building Documentation Site...

ℹ️  Building production site...
   • Compiling React components
   • Optimizing assets
   • Generating static HTML

[==================================] 100%

✅ Build Complete!

📊 Build Statistics:
   • Pages: 42 HTML files
   • Size: 3.2 MB
   • Location: /project/.specweave/docs-site-internal/build/

🚀 Deployment Options:

1️⃣  Netlify:
   cd .specweave/docs-site-internal
   npx netlify deploy --dir=build --prod

2️⃣  Vercel:
   cd .specweave/docs-site-internal
   npx vercel --prod

3️⃣  GitHub Pages:
   cp -r build/* docs/
   git add docs/ && git commit -m "docs: update"
   git push

4️⃣  Static Server (local test):
   npx serve build/

5️⃣  Your own server:
   scp -r build/* user@server:/var/www/docs/
```

## Common Build Errors

### Invalid Frontmatter
```
Error: Invalid frontmatter in file: spec-001.md
```
**Fix:**
```markdown
---
title: User Authentication
sidebar_position: 1
---

Content here...
```

### Broken Links
```
Error: Broken link in file: architecture/hld.md
Link: ../specs/missing-file.md
```
**Fix:** Update or remove broken links

### Missing Dependencies
```
Error: Module not found: 'react'
```
**Fix:**
```bash
cd .specweave/docs-site-internal
npm install
```

## Build vs Preview

| Aspect | Preview (`/specweave-docs-preview:preview`) | Build (`/specweave-docs-preview:build`) |
|--------|---------------------------------------------|----------------------------------------|
| **Purpose** | Development, hot reload | Production deployment |
| **Speed** | Instant start | 5-10 seconds build |
| **Output** | Dev server | Static files |
| **Hot Reload** | ✅ Yes | ❌ No |
| **Optimization** | ❌ No | ✅ Yes (minified, compressed) |
| **Search** | ✅ Works | ✅ Pre-generated index |
| **Use When** | Editing docs | Deploying to server |

## Best Practices

### 1. Build Before Every Deployment
Always build fresh before deploying:
```bash
/specweave-docs-preview:build
# Then deploy
```

### 2. Test Build Locally
```bash
/specweave-docs-preview:build
cd .specweave/docs-site-internal
npx serve build/
# Visit http://localhost:3000 and test
```

### 3. Check All Pages
- Click through every page
- Test search functionality
- Verify all links work
- Check mobile responsiveness

### 4. Optimize Images
Before building, optimize images:
```bash
# Install sharp-cli
npm install -g sharp-cli

# Optimize images
sharp -i docs/images/*.png -o docs/images/optimized/ -q 80
```

### 5. Update Sitemap
The sitemap is auto-generated, but verify it:
```bash
cat .specweave/docs-site-internal/build/sitemap.xml
```

## Integration with CI/CD

### GitHub Actions

**.github/workflows/docs.yml:**
```yaml
name: Deploy Docs

on:
  push:
    branches: [main]
    paths:
      - '.specweave/docs/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20

      - name: Install SpecWeave
        run: npm install -g specweave

      - name: Build Docs
        run: specweave docs build

      - name: Deploy to Netlify
        run: |
          cd .specweave/docs-site-internal
          npx netlify deploy --dir=build --prod
        env:
          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_TOKEN }}
```

## See Also

- `/specweave-docs-preview:preview` - Preview docs locally with hot reload
- `specweave-docs` plugin - Documentation workflow skills
- Docusaurus docs: https://docusaurus.io/docs/deployment