---
name: docs-preview
description: Documentation preview expert for Docusaurus integration. Launches interactive preview server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
---

# 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
```bash
/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`):
```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
```bash
/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`):
```javascript
{
  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
```json
{
  "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
```json
{
  "documentation": {
    "preview": {
      "theme": "default"
    }
  }
}
```

**Available themes:**
- `default` - SpecWeave blue theme
- `classic` - Docusaurus default theme
- `dark` - Dark mode theme

### Exclude Folders
```json
{
  "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:
  ```markdown
  ---
  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

```bash
# 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