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/docs-site-internal/ or .specweave/docs-site-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)

specweave docs          # simplest — launches internal preview
specweave docs preview  # explicit form
/sw-docs:view           # via skill

What it does:

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

View Public Documentation

specweave docs public               # simplest
specweave docs preview --scope public  # explicit form
/sw-docs:view --scope public        # via skill

What it does:

1. Checks if .specweave/docs/public/ exists
2. Runs pre-flight validation (auto-fixes common issues)
3. Sets up Docusaurus in .specweave/docs-site-public/ (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

Docs Type	Port	Path
Internal (default)	3015	.specweave/docs/internal/
Public	3016	.specweave/docs/public/

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/docs-site-internal
# Then run specweave docs again

# For public docs
rm -rf .specweave/docs-site-public
# Then run specweave docs 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