Initial commit

2025-11-29 17:56:31 +08:00
commit ab497cabe8
6 changed files with 1301 additions and 0 deletions
--- a/skills/docs-preview/SKILL.md
+++ b/skills/docs-preview/SKILL.md
@@ -0,0 +1,386 @@
+---
+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