preview
Documentation view expert for Docusaurus integration. Launches interactive server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Works in ANY SpecWeave project with auto-setup. Supports both internal (port 3015) and public (port 3016) docs. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
When & Why to Use This Skill
This Claude skill automates the setup and management of Docusaurus-based documentation for SpecWeave projects. It eliminates manual configuration by launching interactive servers with hot-reload, auto-generated sidebars, and Mermaid diagram support. By handling port management and bypassing private registry issues, it provides a seamless 'living documentation' experience for both internal and public-facing technical docs.
Use Cases
- Instant Documentation Preview: Launch a local server to visualize markdown changes and architecture diagrams in real-time with hot-reload.
- Multi-Environment Management: Simultaneously run and view internal documentation on port 3015 and public-facing docs on port 3016.
- Automated Static Site Generation: Build production-ready static websites from SpecWeave projects for deployment to any hosting service.
- Corporate Environment Compatibility: Bypass private npm registry restrictions (like Azure DevOps) using the skill's built-in public registry configuration.
- Zero-Config Documentation Setup: Automatically initialize Docusaurus in any SpecWeave project without manual installation or folder structuring.
| name | preview |
|---|---|
| description | Documentation view expert for Docusaurus integration. Launches interactive server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Works in ANY SpecWeave project with auto-setup. Supports both internal (port 3015) and public (port 3016) docs. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build. |
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
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/
- Creates Docusaurus in
Subsequent runs (instant):
- Uses cached installation
- Starts server immediately
Available Commands
View Internal Documentation (Default)
/sw-docs:view
What it does:
- Checks if
.specweave/docs/internal/exists - Runs pre-flight validation (auto-fixes common issues)
- Sets up Docusaurus in cache (if first run)
- Starts dev server on http://localhost:3015
- Enables hot reload
View Public Documentation
/sw-docs:view --public
What it does:
- Checks if
.specweave/docs/public/exists - Runs pre-flight validation (auto-fixes common issues)
- Sets up Docusaurus in cache (if first run)
- Starts dev server on http://localhost:3016
- Enables hot reload
Build Static Site
/sw-docs:build
What it does:
- Builds production-ready static site
- Outputs to
.specweave/cache/docs-site/build/ - 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/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