Documentation View Skill

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

What I Do

I help you view your SpecWeave living documentation with Docusaurus:

Key Features

• Zero-config setup – Works in any SpecWeave project automatically
• Internal & Public docs – Internal on port 3015, public on port 3016
• Cached installation – Docusaurus cached in .specweave/cache/docs-site/ (gitignored)
• Hot reload – Edit markdown, see changes instantly
• Mermaid diagrams – Architecture diagrams render beautifully
• Auto sidebar – Generated from folder structure
• Bypasses private registries – Uses public npm to avoid Azure DevOps/corporate issues

How It Works

1. First run (~30 seconds):

   • Creates Docusaurus in .specweave/cache/docs-site/ (internal) or .specweave/cache/docs-site-public/ (public)
   • Installs dependencies from public npm registry
   • Configures to read from .specweave/docs/internal/ or .specweave/docs/public/

2. Subsequent runs (instant):

   • Uses cached installation
   • Starts server immediately

Available Commands

View Internal Documentation (Default)

/sw-docs:view

What it does:

1. Checks if .specweave/docs/internal/ exists
2. Runs pre-flight validation (auto-fixes common issues)
3. Sets up Docusaurus in cache (if first run)
4. Starts dev server on http://localhost:3015
5. Enables hot reload

View Public Documentation

/sw-docs:view --public

What it does:

1. Checks if .specweave/docs/public/ exists
2. Runs pre-flight validation (auto-fixes common issues)
3. Sets up Docusaurus in cache (if first run)
4. Starts dev server on http://localhost:3016
5. Enables hot reload

Build Static Site

/sw-docs:build

What it does:

1. Builds production-ready static site
2. Outputs to .specweave/cache/docs-site/build/
3. Ready for deployment to any static host

When to Use This Skill

Activate for:

• “View my documentation”
• “Preview my docs”
• “Show me my docs in a browser”
• “Launch Docusaurus”
• “View my living documentation”
• “Start docs server”
• “I want to see my internal docs”
• “View public docs”

Workflow

User: "I want to preview my docs"
You: "I'll launch the documentation view server."
     [Run: /sw-docs:view]

User: "Show me my public documentation"
You: "I'll launch the public documentation server."
     [Run: /sw-docs:view --public]

Port Reference

Troubleshooting

Port 3015 or 3016 already in use

# For internal docs
lsof -i :3015 && kill -9 $(lsof -t -i :3015)

# For public docs
lsof -i :3016 && kill -9 $(lsof -t -i :3016)

Reinstall from scratch

# For internal docs
rm -rf .specweave/cache/docs-site
# Then run /sw-docs:view again

# For public docs
rm -rf .specweave/cache/docs-site-public
# Then run /sw-docs:view --public again

npm registry issues

The setup explicitly uses --registry=https://registry.npmjs.org to bypass private/corporate registry configurations.

See Also

• /sw-docs:build – Build static site for deployment
• /sw-docs:organize – Organize large folders with themed indexes
• /sw-docs:health – Documentation health report
• /sw-docs:validate – Validate documentation before viewing