Initial commit
This commit is contained in:
Zhongwei Li
15
.claude-plugin/plugin.json
Normal file
15
.claude-plugin/plugin.json
Normal file
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"name": "specweave-docs-preview",
|
||||
"description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
|
||||
"version": "0.24.0",
|
||||
"author": {
|
||||
"name": "SpecWeave Team",
|
||||
"url": "https://spec-weave.com"
|
||||
},
|
||||
"skills": [
|
||||
"./skills"
|
||||
],
|
||||
"commands": [
|
||||
"./commands"
|
||||
]
|
||||
}
|
||||
3
README.md
Normal file
3
README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# specweave-docs-preview
|
||||
|
||||
Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.
|
||||
489
commands/build.md
Normal file
489
commands/build.md
Normal 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
355
commands/preview.md
Normal 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
|
||||
53
plugin.lock.json
Normal file
53
plugin.lock.json
Normal file
@@ -0,0 +1,53 @@
|
||||
{
|
||||
"$schema": "internal://schemas/plugin.lock.v1.json",
|
||||
"pluginId": "gh:anton-abyzov/specweave:plugins/specweave-docs-preview",
|
||||
"normalized": {
|
||||
"repo": null,
|
||||
"ref": "refs/tags/v20251128.0",
|
||||
"commit": "cacf1d005f124667051e4710d4e0c1e9fb635453",
|
||||
"treeHash": "685fca3af4a60fe02a1f036472ebafaafb0f1fe3c267cbcecd871b607c77118d",
|
||||
"generatedAt": "2025-11-28T10:13:51.295296Z",
|
||||
"toolVersion": "publish_plugins.py@0.2.0"
|
||||
},
|
||||
"origin": {
|
||||
"remote": "git@github.com:zhongweili/42plugin-data.git",
|
||||
"branch": "master",
|
||||
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
|
||||
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
|
||||
},
|
||||
"manifest": {
|
||||
"name": "specweave-docs-preview",
|
||||
"description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
|
||||
"version": "0.24.0"
|
||||
},
|
||||
"content": {
|
||||
"files": [
|
||||
{
|
||||
"path": "README.md",
|
||||
"sha256": "03f94ed129ecf6d3a5344241504bf639674c248698e9a5f2386bb3c58f8fa0eb"
|
||||
},
|
||||
{
|
||||
"path": ".claude-plugin/plugin.json",
|
||||
"sha256": "9f2b28219e85995d6527df7596663ca503f6941b4d39b36637faaeb8ed4fe7bb"
|
||||
},
|
||||
{
|
||||
"path": "commands/preview.md",
|
||||
"sha256": "7a5de767dd3e30aa2da350f88287d4e6a7e2f8eef9a395178a50773cfe93814f"
|
||||
},
|
||||
{
|
||||
"path": "commands/build.md",
|
||||
"sha256": "7962590b279a57419aeaaf11b990b578afac1b6e7b0d8ba5413346fd71434b9b"
|
||||
},
|
||||
{
|
||||
"path": "skills/docs-preview/SKILL.md",
|
||||
"sha256": "a7857fc64007d18634a74492d3d7ab13e7db67e0d1337a436b988300ca6221a0"
|
||||
}
|
||||
],
|
||||
"dirSha256": "685fca3af4a60fe02a1f036472ebafaafb0f1fe3c267cbcecd871b607c77118d"
|
||||
},
|
||||
"security": {
|
||||
"scannedAt": null,
|
||||
"scannerVersion": null,
|
||||
"flags": []
|
||||
}
|
||||
}
|
||||
386
skills/docs-preview/SKILL.md
Normal file
386
skills/docs-preview/SKILL.md
Normal file
@@ -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
|
||||
Reference in New Issue
Block a user