zhongwei/gh-anton-abyzov-specweave-plugins-specweave-docs-preview
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 17:56:31 +08:00
commit ab497cabe8
6 changed files with 1301 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

489
commands/build.md Normal file
View File

@@ -0,0 +1,489 @@
---
name: specweave-docs-preview:build
description: Build static documentation site for deployment. Generates production-ready HTML/CSS/JS files optimized for static hosting.
---
# Documentation Build Command
Build a production-ready static documentation site from your SpecWeave living documentation.
## Your Task
Execute the following workflow to build the static documentation site:
### Step 1: Load the Build Utilities
```typescript
import { buildStaticSite, isSetupNeeded } from '../../../src/utils/docs-preview/index.js';
import * as fs from 'fs-extra';
import * as path from 'path';
```
### Step 2: Check Prerequisites
```typescript
const projectRoot = process.cwd();
// Check if docs preview is configured
const configPath = path.join(projectRoot, '.specweave', 'config.json');
let config: any = {};
if (fs.existsSync(configPath)) {
config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
}
const docsConfig = config.documentation?.preview || {};
console.log('\n📦 Building Documentation Site...\n');
// Check if Docusaurus is installed
const setupNeeded = await isSetupNeeded(projectRoot);
if (setupNeeded) {
console.error('❌ Docusaurus not installed\n');
console.log('💡 Solution:');
console.log(' Run: /specweave-docs-preview:preview');
console.log(' This will install Docusaurus first\n');
process.exit(1);
}
```
### Step 3: Build the Static Site
```typescript
try {
console.log('ℹ️ Building production site...');
console.log(' • Compiling React components');
console.log(' • Optimizing assets');
console.log(' • Generating static HTML\n');
await buildStaticSite(projectRoot);
const buildPath = path.join(projectRoot, '.specweave', 'docs-site-internal', 'build');
const buildStats = await getBuildStats(buildPath);
console.log('\n✅ Build Complete!\n');
console.log('📊 Build Statistics:');
console.log(` • Pages: ${buildStats.pages} HTML files`);
console.log(` • Size: ${buildStats.totalSize}`);
console.log(` • Location: ${buildPath}\n`);
console.log('🚀 Deployment Options:\n');
console.log('1️⃣ Netlify:');
console.log(' cd .specweave/docs-site-internal');
console.log(' npx netlify deploy --dir=build --prod\n');
console.log('2️⃣ Vercel:');
console.log(' cd .specweave/docs-site-internal');
console.log(' npx vercel --prod\n');
console.log('3️⃣ GitHub Pages:');
console.log(' cp -r build/* docs/');
console.log(' git add docs/ && git commit -m "docs: update"');
console.log(' git push\n');
console.log('4️⃣ Static Server (local test):');
console.log(' npx serve build/\n');
console.log('5️⃣ Your own server:');
console.log(' scp -r build/* user@server:/var/www/docs/\n');
} catch (error: any) {
console.error('\n❌ Build Failed\n');
console.error(`Error: ${error.message}\n`);
console.log('💡 Troubleshooting:');
console.log(' • Check all markdown files have valid frontmatter');
console.log(' • Ensure no broken internal links');
console.log(' • Run preview first to catch errors: /specweave-docs-preview:preview');
console.log(' • Check build logs above for specific errors\n');
process.exit(1);
}
```
### Step 4: Helper Function - Get Build Statistics
```typescript
async function getBuildStats(buildPath: string): Promise<{
pages: number;
totalSize: string;
}> {
let pages = 0;
let totalBytes = 0;
async function walk(dir: string) {
const files = await fs.readdir(dir);
for (const file of files) {
const filePath = path.join(dir, file);
const stats = await fs.stat(filePath);
if (stats.isDirectory()) {
await walk(filePath);
} else {
totalBytes += stats.size;
if (file.endsWith('.html')) {
pages++;
}
}
}
}
await walk(buildPath);
const totalMB = (totalBytes / 1024 / 1024).toFixed(2);
return {
pages,
totalSize: `${totalMB} MB`
};
}
```
## What Gets Built
### Output Directory Structure
```
.specweave/docs-site-internal/build/
├── index.html ← Landing page
├── docs/
│ ├── strategy/
│ │ ├── prd-001/
│ │ │ └── index.html
│ │ └── okrs/
│ │ └── index.html
│ ├── specs/
│ │ ├── spec-001-auth/
│ │ │ └── index.html
│ │ └── spec-002-payments/
│ │ └── index.html
│ └── architecture/
│ ├── hld-system/
│ │ └── index.html
│ └── adr/
│ └── 0001-database-choice/
│ └── index.html
├── assets/
│ ├── css/
│ │ └── styles.[hash].css ← Optimized CSS
│ ├── js/
│ │ └── runtime.[hash].js ← React runtime
│ └── images/ ← Optimized images
└── sitemap.xml ← Search engine sitemap
```
### Build Optimizations
1. **Code Splitting**: React chunks loaded on demand
2. **Asset Optimization**: CSS/JS minified and compressed
3. **Image Optimization**: Auto-resized and compressed
4. **Static HTML**: Pre-rendered pages for fast loading
5. **Search Index**: Pre-generated search index
6. **Sitemap**: Auto-generated for SEO
## Deployment Examples
### Netlify (Recommended)
**Option 1: CLI**
```bash
cd .specweave/docs-site-internal
npx netlify deploy --dir=build --prod
```
**Option 2: Drag & Drop**
1. Go to https://app.netlify.com/drop
2. Drag `.specweave/docs-site-internal/build/` folder
3. Done! Get instant URL
**Option 3: Git Integration**
1. Create `netlify.toml`:
```toml
[build]
base = ".specweave/docs-site-internal"
publish = "build"
command = "npm run build"
```
2. Connect GitHub repo
3. Auto-deploy on push
### Vercel
```bash
cd .specweave/docs-site-internal
npx vercel --prod
```
### GitHub Pages
**Option 1: docs/ folder**
```bash
# 1. Copy build to docs/
cp -r .specweave/docs-site-internal/build/* docs/
# 2. Enable GitHub Pages
# Go to Settings → Pages → Source: main branch /docs folder
# 3. Push
git add docs/
git commit -m "docs: update documentation site"
git push
```
**Option 2: gh-pages branch**
```bash
# 1. Install gh-pages
npm install -g gh-pages
# 2. Deploy
gh-pages -d .specweave/docs-site-internal/build
```
### AWS S3 + CloudFront
```bash
# 1. Sync to S3
aws s3 sync .specweave/docs-site-internal/build/ s3://your-bucket/ \
--delete \
--cache-control "max-age=31536000,public"
# 2. Invalidate CloudFront
aws cloudfront create-invalidation \
--distribution-id YOUR_DIST_ID \
--paths "/*"
```
### Docker + Nginx
**Dockerfile:**
```dockerfile
FROM nginx:alpine
COPY .specweave/docs-site-internal/build/ /usr/share/nginx/html/
EXPOSE 80
```
**Build and run:**
```bash
docker build -t docs .
docker run -p 80:80 docs
```
### Your Own Server
**Nginx config:**
```nginx
server {
listen 80;
server_name docs.example.com;
root /var/www/docs;
index index.html;
location / {
try_files $uri $uri/ /index.html;
}
}
```
**Deploy:**
```bash
scp -r .specweave/docs-site-internal/build/* user@server:/var/www/docs/
```
## Testing Before Deployment
### Local Testing with Serve
```bash
# 1. Install serve
npm install -g serve
# 2. Serve build folder
cd .specweave/docs-site-internal
serve build/
# 3. Open browser
# Visit: http://localhost:3000
```
### Check Lighthouse Scores
```bash
# 1. Install lighthouse
npm install -g lighthouse
# 2. Run audit
lighthouse http://localhost:3000 \
--view \
--output html
# Expected scores:
# Performance: 100
# Accessibility: 100
# Best Practices: 100
# SEO: 100
```
## Expected Output
**Successful Build:**
```
📦 Building Documentation Site...
ℹ️ Building production site...
• Compiling React components
• Optimizing assets
• Generating static HTML
[==================================] 100%
✅ Build Complete!
📊 Build Statistics:
• Pages: 42 HTML files
• Size: 3.2 MB
• Location: /project/.specweave/docs-site-internal/build/
🚀 Deployment Options:
1️⃣ Netlify:
cd .specweave/docs-site-internal
npx netlify deploy --dir=build --prod
2️⃣ Vercel:
cd .specweave/docs-site-internal
npx vercel --prod
3️⃣ GitHub Pages:
cp -r build/* docs/
git add docs/ && git commit -m "docs: update"
git push
4️⃣ Static Server (local test):
npx serve build/
5️⃣ Your own server:
scp -r build/* user@server:/var/www/docs/
```
## Common Build Errors
### Invalid Frontmatter
```
Error: Invalid frontmatter in file: spec-001.md
```
**Fix:**
```markdown
---
title: User Authentication
sidebar_position: 1
---
Content here...
```
### Broken Links
```
Error: Broken link in file: architecture/hld.md
Link: ../specs/missing-file.md
```
**Fix:** Update or remove broken links
### Missing Dependencies
```
Error: Module not found: 'react'
```
**Fix:**
```bash
cd .specweave/docs-site-internal
npm install
```
## Build vs Preview
| Aspect | Preview (`/specweave-docs-preview:preview`) | Build (`/specweave-docs-preview:build`) |
|--------|---------------------------------------------|----------------------------------------|
| **Purpose** | Development, hot reload | Production deployment |
| **Speed** | Instant start | 5-10 seconds build |
| **Output** | Dev server | Static files |
| **Hot Reload** | ✅ Yes | ❌ No |
| **Optimization** | ❌ No | ✅ Yes (minified, compressed) |
| **Search** | ✅ Works | ✅ Pre-generated index |
| **Use When** | Editing docs | Deploying to server |
## Best Practices
### 1. Build Before Every Deployment
Always build fresh before deploying:
```bash
/specweave-docs-preview:build
# Then deploy
```
### 2. Test Build Locally
```bash
/specweave-docs-preview:build
cd .specweave/docs-site-internal
npx serve build/
# Visit http://localhost:3000 and test
```
### 3. Check All Pages
- Click through every page
- Test search functionality
- Verify all links work
- Check mobile responsiveness
### 4. Optimize Images
Before building, optimize images:
```bash
# Install sharp-cli
npm install -g sharp-cli
# Optimize images
sharp -i docs/images/*.png -o docs/images/optimized/ -q 80
```
### 5. Update Sitemap
The sitemap is auto-generated, but verify it:
```bash
cat .specweave/docs-site-internal/build/sitemap.xml
```
## Integration with CI/CD
### GitHub Actions
**.github/workflows/docs.yml:**
```yaml
name: Deploy Docs
on:
push:
branches: [main]
paths:
- '.specweave/docs/**'
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 20
- name: Install SpecWeave
run: npm install -g specweave
- name: Build Docs
run: specweave docs build
- name: Deploy to Netlify
run: |
cd .specweave/docs-site-internal
npx netlify deploy --dir=build --prod
env:
NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_TOKEN }}
```
## See Also
- `/specweave-docs-preview:preview` - Preview docs locally with hot reload
- `specweave-docs` plugin - Documentation workflow skills
- Docusaurus docs: https://docusaurus.io/docs/deployment

355
commands/preview.md Normal file
View File

@@ -0,0 +1,355 @@
---
name: specweave-docs-preview:preview
description: Launch interactive documentation preview server with Docusaurus. Auto-generates sidebar, enables hot reload, and opens browser automatically.
---
# Documentation Preview Command
Launch an interactive Docusaurus development server to preview your SpecWeave living documentation.
## 🎨 Beautiful Docusaurus Experience
**This command ALWAYS uses Docusaurus** - not basic file serving! You get:
- ✅ Auto-generated navigation from folder structure
- ✅ Search functionality (instant local search)
- ✅ Beautiful theming (light/dark mode)
- ✅ Mermaid diagram rendering
- ✅ Hot reload (edit markdown, see changes instantly)
- ✅ Professional typography and layout
- ✅ Mobile responsive design
**Never settle for basic markdown rendering when you can have this!**
## Your Task
Execute the following workflow to launch the documentation preview server:
### Step 1: Load the Preview Utilities
```typescript
import { launchPreview, isSetupNeeded, getDocsSitePath } from '../../../src/utils/docs-preview/index.js';
```
**Note:** These utilities are already implemented in the SpecWeave codebase.
### Step 2: Check Configuration
Read the project configuration from `.specweave/config.json`:
```typescript
import * as fs from 'fs-extra';
import * as path from 'path';
const projectRoot = process.cwd();
const configPath = path.join(projectRoot, '.specweave', 'config.json');
let config: any = {};
if (fs.existsSync(configPath)) {
config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
}
const docsConfig = config.documentation?.preview || {
enabled: true,
autoInstall: true,
port: 3016,
openBrowser: true,
theme: 'default',
excludeFolders: ['legacy', 'node_modules']
};
```
### Step 3: Check if Documentation Preview is Enabled (Auto-Enable if Needed)
```typescript
if (!docsConfig.enabled) {
console.log('📚 Documentation preview is currently disabled.');
console.log(' Enabling it now for beautiful Docusaurus experience...\n');
// Auto-enable the feature
config.documentation = config.documentation || {};
config.documentation.preview = {
...docsConfig,
enabled: true,
autoInstall: true
};
// Save updated config
fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
console.log('✅ Documentation preview enabled!\n');
}
```
### Step 4: Display Setup Information
```typescript
console.log('\n📚 Launching Documentation Preview...\n');
const setupNeeded = await isSetupNeeded(projectRoot);
if (setupNeeded) {
console.log('ℹ️ First-time setup required');
console.log(' • Installing Docusaurus (~30 seconds)');
console.log(' • Generating configuration');
console.log(' • Creating sidebar from folder structure\n');
} else {
console.log('✓ Docusaurus already installed');
console.log('✓ Configuration up-to-date\n');
}
```
### Step 5: Launch the Preview Server
```typescript
try {
const options = {
port: docsConfig.port || 3016,
openBrowser: docsConfig.openBrowser !== false,
theme: docsConfig.theme || 'default',
excludeFolders: docsConfig.excludeFolders || ['legacy', 'node_modules']
};
const server = await launchPreview(projectRoot, options);
console.log('\n✅ Documentation server started successfully!\n');
console.log(`🌐 URL: ${server.url}`);
console.log('🔄 Hot reload enabled - edit markdown files to see changes instantly');
console.log('🗂️ Sidebar auto-generated from folder structure');
console.log('📊 Mermaid diagrams supported');
console.log('\n💡 Press Ctrl+C to stop the server\n');
// Keep the process running
process.on('SIGINT', () => {
console.log('\n\n👋 Stopping documentation server...');
process.exit(0);
});
} catch (error: any) {
console.error('\n❌ Failed to launch documentation preview\n');
console.error(`Error: ${error.message}\n`);
if (error.message.includes('Node.js 18+')) {
console.log('💡 Solution:');
console.log(' • Update Node.js: nvm install 20 (or download from nodejs.org)');
console.log(' • Current version: node --version\n');
} else if (error.message.includes('port')) {
console.log('💡 Solution:');
console.log(' • Change port in .specweave/config.json');
console.log(' • Or stop the service using port ' + (docsConfig.port || 3016));
console.log(' • Check with: lsof -i :' + (docsConfig.port || 3016) + '\n');
} else {
console.log('💡 Troubleshooting:');
console.log(' • Check Node.js version (18+ required): node --version');
console.log(' • Clear npm cache: npm cache clean --force');
console.log(' • Check .specweave/docs/internal/ exists');
console.log(' • Run with DEBUG=* for detailed logs\n');
}
process.exit(1);
}
```
## Important Notes
### Configuration
The command uses settings from `.specweave/config.json`:
```json
{
"documentation": {
"preview": {
"enabled": true,
"autoInstall": true,
"port": 3016,
"openBrowser": true,
"theme": "default",
"excludeFolders": ["legacy", "node_modules"]
}
}
}
```
### First-Time Setup
On first run, the command will:
1. Check Node.js version (requires 18+)
2. Install Docusaurus packages (~30 seconds)
3. Generate `docusaurus.config.js`
4. Create sidebar from folder structure
5. Start development server
6. Open browser automatically
### Subsequent Runs
On subsequent runs, the command will:
1. Check if Docusaurus is installed (instant)
2. Regenerate sidebar (in case docs changed)
3. Start server (~2 seconds)
4. Open browser
### Directory Structure
```
.specweave/
├── docs/
│ └── internal/ ← Source documentation
│ ├── strategy/
│ ├── specs/
│ ├── architecture/
│ ├── delivery/
│ ├── operations/
│ └── governance/
└── docs-site-internal/ ← Docusaurus installation (generated)
├── docs/ ← Symlinked to internal/
├── src/
├── docusaurus.config.js
├── sidebars.js
└── package.json
```
### What Gets Auto-Generated
1. **Sidebar** (`sidebars.js`):
- Recursively scans `.specweave/docs/internal/`
- Creates categories from folders
- Sorts by priority (strategy first, governance last)
- Formats labels (kebab-case → Title Case)
2. **Configuration** (`docusaurus.config.js`):
- Site title from project name
- Theme settings from config
- Mermaid diagram support
- Hot reload enabled
3. **Landing Page** (`src/pages/index.js`):
- Welcome message
- Quick navigation links
- Project information
### Hot Reload
Changes to markdown files in `.specweave/docs/internal/` are detected automatically:
- Edit file → Save → Browser refreshes instantly
- No need to restart server
- Works for all markdown files
### Stopping the Server
- Press `Ctrl+C` in terminal
- Or close the terminal window
- Or kill the process: `pkill -f docusaurus`
## Expected Output
**First Run:**
```
📚 Launching Documentation Preview...
ℹ️ First-time setup required
• Installing Docusaurus (~30 seconds)
• Generating configuration
• Creating sidebar from folder structure
📦 Installing Docusaurus packages...
[============================>] 100%
✓ Packages installed successfully
✓ Configuration generated
✓ Sidebar generated (42 documents, 8 categories)
✓ Server started on http://localhost:3016
✅ Documentation server started successfully!
🌐 URL: http://localhost:3016
🔄 Hot reload enabled - edit markdown files to see changes instantly
🗂️ Sidebar auto-generated from folder structure
📊 Mermaid diagrams supported
💡 Press Ctrl+C to stop the server
```
**Subsequent Runs:**
```
📚 Launching Documentation Preview...
✓ Docusaurus already installed
✓ Configuration up-to-date
✓ Sidebar generated (42 documents, 8 categories)
✓ Server started on http://localhost:3016
✅ Documentation server started successfully!
🌐 URL: http://localhost:3016
🔄 Hot reload enabled - edit markdown files to see changes instantly
🗂️ Sidebar auto-generated from folder structure
📊 Mermaid diagrams supported
💡 Press Ctrl+C to stop the server
```
## Troubleshooting
### Common Issues
**Port Already in Use:**
```
Error: Port 3016 is already in use
```
Solution:
1. Change port in `.specweave/config.json` → `documentation.preview.port`
2. Or stop the service: `lsof -i :3016` then `kill -9 <PID>`
**Node.js Version:**
```
Error: Node.js 18+ required (current: v16.x.x)
```
Solution:
1. Update Node.js: `nvm install 20` (or download from nodejs.org)
2. Verify: `node --version`
**Missing Documentation:**
```
Error: No documentation found in .specweave/docs/internal/
```
Solution:
1. Check folder exists: `ls .specweave/docs/internal/`
2. Add at least one markdown file
3. Or run `/specweave:increment` to create documentation
## Integration with SpecWeave Workflow
### After Creating Increment
```bash
/specweave:increment "User Authentication"
# → Creates spec.md, plan.md, tasks.md
/specweave-docs-preview:preview
# → Preview shows new spec in sidebar
```
### After Completing Increment
```bash
/specweave:done 0008
# → Syncs spec.md to .specweave/docs/internal/specs/spec-0008-user-auth.md
# Hot reload automatically shows the new spec!
# No need to restart preview server
```
### Viewing Architecture Decisions
```bash
# Create ADR
vim .specweave/docs/internal/architecture/adr/0001-database-choice.md
# Hot reload shows it instantly
# Navigate to Architecture → ADR → Database Choice
```
## Best Practices
1. **Keep Server Running**: Start once, leave running during development
2. **Edit in IDE**: Changes reflect instantly (hot reload)
3. **Organize Folders**: Good folder structure = good sidebar
4. **Use Frontmatter**: Add title, position to control order
5. **Test Search**: Built-in search works after indexing
## See Also
- `/specweave-docs-preview:build` - Build static site for deployment
- `specweave-docs` plugin - General documentation skills
- Docusaurus docs: https://docusaurus.io