Documentation Preview Skill

Expert in launching and managing Docusaurus documentation preview for SpecWeave projects.

What I Do

I help you preview and build your SpecWeave living documentation with Docusaurus:

1. Interactive Preview

• Launch local development server (default port: 3015)
• Auto-generate sidebar from folder structure
• Hot reload - edit markdown, see changes instantly
• Mermaid diagram rendering
• Mobile-responsive UI
• Search functionality

2. Static Site Building

• Build production-ready static site
• Output to .specweave/docs-site-internal/build/
• Ready for deployment to any static host
• Optimized for performance

3. Smart Setup

• Lazy installation (only installs when first used)
• Checks Node.js version (18+ required)
• Installs Docusaurus dependencies automatically
• Configures from .specweave/config.json settings

Available Commands

Preview Documentation

/specweave-docs-preview:preview

What it does:

1. Checks if Docusaurus is installed (installs if needed)
2. Generates sidebar from .specweave/docs/internal/ structure
3. Starts development server on port 3015 (configurable)
4. Opens browser automatically
5. Enables hot reload

Configuration (.specweave/config.json):

{
  "documentation": {
    "preview": {
      "enabled": true,
      "autoInstall": false,
      "port": 3015,
      "openBrowser": true,
      "theme": "default",
      "excludeFolders": ["legacy", "node_modules"]
    }
  }
}

Example session:

User: "Can I preview my documentation?"
You: "Yes! I'll launch the Docusaurus preview server for you."
     [Run: /specweave-docs-preview:preview]

Output:
📚 Setting up documentation preview...
✓ Node.js version check passed (v20.0.0)
✓ Docusaurus already installed
✓ Sidebar generated (42 documents, 8 categories)
✓ Server started on http://localhost:3015

🌐 Documentation available at: http://localhost:3015
🔄 Hot reload enabled - edit docs and see changes instantly
💡 Press Ctrl+C to stop the server

Build Static Site

/specweave-docs-preview:build

What it does:

1. Checks if Docusaurus is installed
2. Runs production build
3. Outputs to .specweave/docs-site-internal/build/
4. Shows build stats and output path

Example session:

User: "Build my docs for deployment"
You: "I'll build the static documentation site."
     [Run: /specweave-docs-preview:build]

Output:
📦 Building static documentation site...
✓ Build complete!
📁 Output: /project/.specweave/docs-site-internal/build/

To deploy:
1. Copy build/ folder to your static host
2. Or use: npx serve build/

When to Use This Skill

Activate for questions like:

• "How do I preview my documentation?"
• "Show me my docs in a UI"
• "Launch Docusaurus server"
• "View my living documentation"
• "Start docs preview"
• "Build static docs site"
• "Hot reload documentation"
• "Documentation website"

Common workflows:

1. First-time preview:

User: "I want to preview my docs"
You: "I'll set up the documentation preview with Docusaurus.
      This will install dependencies (takes ~30 seconds first time)."
     [Run: /specweave-docs-preview:preview]

2. Already running:

User: "Preview my docs"
You: "Checking if Docusaurus is running..."
     [If running: "Documentation server already running at http://localhost:3015"]
     [If not: Run /specweave-docs-preview:preview]

3. Build for deployment:

User: "I need to deploy my docs"
You: "I'll build the static site for deployment."
     [Run: /specweave-docs-preview:build]
     "Once built, you can deploy the build/ folder to:"
     "• Netlify, Vercel, GitHub Pages"
     "• Any static host (Nginx, Apache, S3)"
     "• Or test locally with: npx serve build/"

Architecture

Folder Structure

.specweave/
├── docs/
│   └── internal/           ← Source documentation
│       ├── strategy/
│       ├── specs/
│       ├── architecture/
│       └── ...
└── docs-site-internal/     ← Docusaurus installation
    ├── docs/               ← Symlinked to internal/
    ├── src/
    ├── build/              ← Static output
    ├── docusaurus.config.js
    ├── sidebars.js         ← Auto-generated
    └── package.json

Sidebar Auto-Generation

The sidebar is generated from your folder structure:

Input (.specweave/docs/internal/):

internal/
├── strategy/
│   ├── prd-001.md
│   └── okrs.md
├── specs/
│   ├── spec-001-auth.md
│   └── spec-002-payments.md
└── architecture/
    ├── hld-system.md
    └── adr/
        └── 0001-database-choice.md

Output (sidebars.js):

{
  docs: [
    {
      type: 'category',
      label: 'Strategy',
      items: ['strategy/prd-001', 'strategy/okrs']
    },
    {
      type: 'category',
      label: 'Specs',
      items: ['specs/spec-001-auth', 'specs/spec-002-payments']
    },
    {
      type: 'category',
      label: 'Architecture',
      items: [
        'architecture/hld-system',
        {
          type: 'category',
          label: 'ADR',
          items: ['architecture/adr/0001-database-choice']
        }
      ]
    }
  ]
}

Configuration Options

Port Selection

{
  "documentation": {
    "preview": {
      "port": 3015
    }
  }
}

Why 3015?

• Port 3000 = React/Next.js/Vite dev servers (conflict!)
• Port 3015 = Internal docs (SpecWeave default)
• Port 3016 = Reserved for public docs (future)

Theme Selection

{
  "documentation": {
    "preview": {
      "theme": "default"
    }
  }
}

Available themes:

• default - SpecWeave blue theme
• classic - Docusaurus default theme
• dark - Dark mode theme

Exclude Folders

{
  "documentation": {
    "preview": {
      "excludeFolders": ["legacy", "node_modules", "archive"]
    }
  }
}

Troubleshooting

Port already in use

Error: Port 3015 is already in use
Solution: Change port in config or stop other service

Node.js version

Error: Node.js 18+ required
Solution: Update Node.js (nvm install 20)

Mermaid diagrams not rendering

Issue: Diagrams show as code blocks
Solution: Use ```mermaid code fences (built-in support)

Build fails

Error: Build failed
Check:
1. All markdown files have valid frontmatter
2. No broken internal links
3. Run preview first to catch errors early

Best Practices

1. Use Preview During Development

• Start preview server: /specweave-docs-preview:preview
• Edit markdown files in .specweave/docs/internal/
• See changes instantly (hot reload)
• No need to rebuild

2. Build Before Deployment

• Always build before deploying
• Test build output locally: npx serve build/
• Check all pages render correctly
• Verify search works

3. Keep Docs Organized

• Follow SpecWeave folder structure
• Use meaningful file names
• Add frontmatter to markdown files:

  ---
  title: User Authentication
  sidebar_position: 1
  ---
  

4. Optimize for Search

• Use descriptive headings
• Include keywords naturally
• Add alt text to images
• Keep URL structure clean

Example: Complete Workflow

# 1. Preview docs locally
/specweave-docs-preview:preview
# → Opens http://localhost:3015
# → Edit files, see changes instantly

# 2. Build for production
/specweave-docs-preview:build
# → Outputs to .specweave/docs-site-internal/build/

# 3. Deploy (example with Netlify)
cd .specweave/docs-site-internal
npx netlify deploy --dir=build --prod

Integration with SpecWeave

Living Documentation Sync

Documentation preview integrates with SpecWeave's living docs:

1. After increment completion:

   • spec.md synced to .specweave/docs/internal/specs/
   • Preview updates automatically (hot reload)

2. Architecture decisions:

   • ADRs created in .specweave/docs/internal/architecture/adr/
   • Instantly visible in preview

3. Multi-project support:

   • Each project gets its own docs folder
   • Preview shows all projects in sidebar

Commands Summary

Command	Purpose	When to Use
/specweave-docs-preview:preview	Launch dev server	During development, hot reload
/specweave-docs-preview:build	Build static site	Before deployment, production

Technical Details

Under the Hood

• Framework: Docusaurus 3.0
• React version: 18+
• Build tool: Webpack 5
• Markdown: MDX support
• Diagrams: Mermaid.js
• Search: Algolia DocSearch (optional)

Performance

• Install time: ~30 seconds (first time only)
• Build time: ~5-10 seconds (small docs)
• Hot reload: <1 second
• Static site: Fully optimized, lighthouse 100

See Also

• specweave-docs skill - General documentation workflows
• spec-generator skill - Generate living docs specs
• sync-docs skill - Sync docs after increments
• Docusaurus docs: https://docusaurus.io