preview

Docusaurus集成的文档查看专家。为SpecWeave活态文档启动交互式服务器,支持热重载、自动生成的侧边栏和Mermaid图表。适用于任何具有自动设置的SpecWeave项目。支持内部(端口3015)和公共(端口3016)文档。针对预览文档、查看文档、Docusaurus服务器、文档UI、文档网站、本地文档服务器、热重载文档、静态站点构建激活。

📖 中文导读:Docusaurus集成的文档查看专家。为SpecWeave活态文档启动交互式服务器,支持热重载、自动生成的侧边栏和Mermaid图表。适用于任何具有自动设置的SpecWeave项目。支持内部(端口3015)和公共(端口3016)文档。针对预览文档、查看文档、Docusaurus服务器、文档UI、文档网站、本地文档服务器、热重载文档、静态站点构建激活。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

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

  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

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