gh-anton-abyzov-specweave-plugins-specweave-docs-preview/commands/preview.md

name, description

name	description
specweave-docs-preview:preview	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

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:

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)

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

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

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:

{
  "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

/specweave:increment "User Authentication"
# → Creates spec.md, plan.md, tasks.md

/specweave-docs-preview:preview
# → Preview shows new spec in sidebar

After Completing Increment

/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

# 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