/docs-view

description: Launch Docusaurus documentation server for living docs. Supports internal (default, port 3015) and public (--public, port 3016) docs. Validates docs first, auto-fixes issues, auto-setup on first run.

Documentation View Command

Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.

**CRITICAL**: Runs pre-flight validation to catch issues BEFORE starting the server.

Usage

# View internal docs (default) - port 3015
/docs:view

# View public docs - port 3016
/docs:view --public
/docs:view public

Your Task

**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.

Step 0: Parse Arguments

// Determine which docs to view
const args = process.argv.slice(2);
const isPublic = args.includes('--public') || args.includes('public');

const config = isPublic
  ? {
      docsPath: '.specweave/docs/public',
      port: 3016,
      title: 'Public Documentation',
      cachePath: '.specweave/cache/docs-site-public',
      navbarTitle: 'Public Docs'
    }
  : {
      docsPath: '.specweave/docs/internal',
      port: 3015,
      title: 'Internal Documentation',
      cachePath: '.specweave/cache/docs-site',
      navbarTitle: 'Internal Docs'
    };

console.log(`\n📚 Starting ${config.title} server...\n`);

Step 1: Check Prerequisites

# Verify docs exist at the selected path
ls -la ${config.docsPath}/

# If missing, inform user:
# "No documentation found at ${config.docsPath}/.
#  Run 'specweave init' first or create the folder structure."

Step 1.5: CRITICAL - Run Pre-Flight Validation

**ALWAYS run validation BEFORE starting the server!**

import { DocsValidator } from '../../../src/utils/docs-validator.js';

const validator = new DocsValidator({
  docsPath: config.docsPath,
  autoFix: true,  // Auto-fix common issues
});

console.log('\n🔍 Running pre-flight validation...\n');
const result = await validator.validate();

// Show summary
console.log(DocsValidator.formatResult(result));

// If errors remain after auto-fix, STOP and report
if (!result.valid) {
  console.log('\n❌ Documentation has errors that must be fixed before preview.');
  console.log('   Fix the issues above, then try again.\n');
  process.exit(1);
}

console.log('\n✅ Validation passed! Starting server...\n');

**What this catches:**

• YAML frontmatter errors (unquoted colons, tabs)
• MDX compatibility issues (unquoted attributes, unclosed tags)
• Duplicate routes
• Broken internal links

**Auto-fixes applied:**

• Wraps YAML values with colons in quotes
• Quotes HTML attributes
• Adds closing slashes to void elements (`<br>` → `<br />`)
• Converts tabs to spaces in YAML

Step 2: Check for Cached Installation

# Check if Docusaurus is already set up in cache
if [ -d "${config.cachePath}/node_modules" ]; then
  echo "✓ Docusaurus installation found in cache"
  NEEDS_INSTALL=false
else
  echo "⚙ First-time setup: Installing Docusaurus (~30 seconds)..."
  NEEDS_INSTALL=true
fi

Step 3: First-Time Setup (if needed)

If `NEEDS_INSTALL=true`, create the cached Docusaurus installation:

import * as fs from 'fs';
import * as path from 'path';
import { execSync } from 'child_process';

// Create cache directory
fs.mkdirSync(config.cachePath, { recursive: true });

// Create package.json
const packageJson = {
  name: isPublic ? 'specweave-docs-public' : 'specweave-docs-internal',
  version: '1.0.0',
  private: true,
  scripts: {
    start: `docusaurus start --port ${config.port}`,
    build: 'docusaurus build',
    clear: 'docusaurus clear'
  },
  dependencies: {
    '@docusaurus/core': '^3.9.2',
    '@docusaurus/preset-classic': '^3.9.2',
    '@docusaurus/theme-mermaid': '^3.9.2',
    '@mdx-js/react': '^3.0.0',
    'clsx': '^2.0.0',
    'prism-react-renderer': '^2.3.0',
    'react': '^19.0.0',
    'react-dom': '^19.0.0'
  },
  engines: {
    node: '>=20.0'
  }
};

fs.writeFileSync(
  path.join(config.cachePath, 'package.json'),
  JSON.stringify(packageJson, null, 2)
);

// Calculate relative path from cache to docs
// For internal: ../../docs/internal
// For public: ../../docs/public
const relativePath = isPublic ? '../../docs/public' : '../../docs/internal';

// Create Docusaurus config
const docusaurusConfig = `import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';
import type * as Preset from '@docusaurus/preset-classic';

const config: Config = {
  title: '${config.title}',
  tagline: 'SpecWeave Living Documentation',
  favicon: 'img/favicon.ico',
  future: { v4: true },
  url: 'http://localhost:${config.port}',
  baseUrl: '/',
  onBrokenLinks: 'warn',
  onBrokenMarkdownLinks: 'warn',
  i18n: { defaultLocale: 'en', locales: ['en'] },
  markdown: { mermaid: true, format: 'md' },
  themes: ['@docusaurus/theme-mermaid'],
  presets: [
    [
      'classic',
      {
        docs: {
          path: '${relativePath}',
          routeBasePath: '/',
          sidebarPath: './sidebars.ts',
          showLastUpdateTime: true,
          sidebarCollapsible: true,
          sidebarCollapsed: true,
        },
        blog: false,
        theme: { customCss: './src/css/custom.css' },
      } satisfies Preset.Options,
    ],
  ],
  themeConfig: {
    colorMode: {
      defaultMode: 'dark',
      disableSwitch: false,
      respectPrefersColorScheme: true,
    },
    navbar: {
      title: '${config.navbarTitle}',
      items: [
        {to: '/', label: 'Home', position: 'left'},
        {type: 'search', position: 'right'},
      ],
    },
    footer: {
      style: 'dark',
      copyright: 'SpecWeave Living Documentation',
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
      additionalLanguages: ['bash', 'typescript', 'yaml', 'json'],
    },
    mermaid: { theme: {light: 'neutral', dark: 'dark'} },
  } satisfies Preset.ThemeConfig,
};