Vapora/docs/mdbook-setup.md

# mdBook Setup for VAPORA Documentation

## Overview

VAPORA documentation is now fully integrated with **mdBook**, a command-line tool for building beautiful books from markdown files. This setup allows automatic generation of a professional-looking website from your existing markdown documentation.

## ✅ What's Been Created

### 1. **Configuration** (`docs/book.toml`)
- mdBook settings (title, source directory, output directory)
- HTML output configuration with custom branding
- GitHub integration for edit links
- Search and print functionality enabled

### 2. **Source Structure** (`docs/src/`)
- **SUMMARY.md** — Table of contents (85+ entries organized by section)
- **intro.md** — Landing page with platform overview and learning paths
- **README.md** — Documentation about the mdBook setup

### 3. **Custom Theme** (`docs/theme/`)
- **vapora-custom.css** — Professional styling with VAPORA branding
  - Blue/violet color scheme matching VAPORA brand
  - Responsive design (mobile-friendly)
  - Dark mode support
  - Custom syntax highlighting
  - Print-friendly styles

### 4. **Build Artifacts** (`docs/book/`)
- Static HTML site (7.4 MB)
- Fully generated and ready for deployment
- Git-ignored (not committed to repository)

### 5. **Git Configuration** (`docs/.gitignore`)
- Excludes build output and temporary files
- Keeps repository clean

## 📖 Directory Structure

```
docs/
├── book.toml                    # mdBook configuration
├── mdbook-setup.md              # This file
├── README.md                    # Main docs README (updated with mdBook info)
├── .gitignore                   # Excludes build artifacts
│
├── src/                         # mdBook source files
│   ├── SUMMARY.md               # Table of contents (85+ entries)
│   ├── intro.md                 # Landing page
│   └── README.md                # mdBook documentation
│
├── theme/                       # Custom styling
│   └── vapora-custom.css        # VAPORA brand styling
│
├── book/                        # Generated output (.gitignored)
│   ├── index.html               # Main page (7.4 MB)
│   ├── print.html               # Printable version
│   ├── css/                     # Stylesheets
│   ├── fonts/                   # Typography
│   └── js/                      # Interactivity
│
├── adrs/                        # Architecture Decision Records (27+ files)
├── architecture/                # System design (6+ files)
├── disaster-recovery/           # Recovery procedures (5+ files)
├── features/                    # Platform capabilities (2+ files)
├── integrations/                # Integration guides (5+ files)
├── operations/                  # Runbooks and procedures (8+ files)
├── setup/                       # Installation & deployment (7+ files)
├── tutorials/                   # Learning tutorials (3+ files)
├── examples-guide.md            # Examples documentation
├── getting-started.md           # Entry point
├── quickstart.md                # Quick setup
└── README.md                    # Main directory index
```

## 🚀 Quick Start

### Install mdBook (if not already installed)

```bash
cargo install mdbook
```

### Build the documentation

```bash
cd docs
mdbook build
```

Output will be in `docs/book/` directory (7.4 MB).

### Serve locally for development

```bash
cd docs
mdbook serve
```

Then open `http://localhost:3000` in your browser.

Changes to markdown files will automatically rebuild the documentation.

### Clean build output

```bash
cd docs
mdbook clean
```

## 📋 What Gets Indexed

The mdBook automatically indexes **85+ documentation entries** organized into:

### Getting Started (2)
- Quick Start
- Quickstart Guide

### Setup & Deployment (7)
- Setup Overview, Setup Guide
- Deployment Guide, Deployment Quickstart
- Tracking Setup, Tracking Quickstart
- SecretumVault Integration

### Features (2)
- Features Overview
- Platform Capabilities

### Architecture (7)
- Architecture Overview, VAPORA Architecture
- Agent Registry & Coordination
- Multi-IA Router, Multi-Agent Workflows
- Task/Agent/Doc Manager
- Roles, Permissions & Profiles

### Architecture Decision Records (27)
- 0001-0027: Complete decision history
- Covers all major technical choices

### Integration Guides (5)
- Doc Lifecycle, RAG Integration
- Provisioning Integration
- And more...

### Examples & Tutorials (4)
- Examples Guide (600+ lines)
- Basic Agents, LLM Routing tutorials

### Operations & Runbooks (8)
- Deployment, Pre-Deployment Checklist
- Monitoring, On-Call Procedures
- Incident Response, Rollback
- Backup & Recovery Automation

### Disaster Recovery (5)
- DR Overview, Runbook
- Backup Strategy
- Database Recovery, Business Continuity

## 🎨 Features

### Built-In Capabilities

✅ **Full-Text Search** — Search documentation instantly
✅ **Dark Mode** — Professional light/dark theme toggle
✅ **Print-Friendly** — Export entire book as PDF
✅ **Edit Links** — Quick link to GitHub editor
✅ **Mobile Responsive** — Optimized for all devices
✅ **Syntax Highlighting** — Beautiful code blocks
✅ **Table of Contents** — Automatic sidebar navigation

### Custom VAPORA Branding

- **Color Scheme**: Blue/violet primary colors
- **Typography**: System fonts + Fira Code for code
- **Responsive Design**: Desktop, tablet, mobile optimized
- **Dark Mode**: Full support with proper contrast

## 📝 Content Guidelines

### File Naming
- Root markdown: **UPPERCASE** (README.md)
- Content markdown: **lowercase** (setup-guide.md)
- Multi-word: **kebab-case** (setup-guide.md)

### Markdown Standards
1. **Code Blocks**: Language specified (bash, rust, toml)
2. **Lists**: Blank line before and after
3. **Headings**: Proper hierarchy (h2 → h3 → h4)
4. **Links**: Relative paths only (`../section/file.md`)

### Internal Links Pattern

```markdown
# Correct (relative paths)
- [Setup Guide](../setup/setup-guide.md)
- [ADR 0001](../adrs/0001-cargo-workspace.md)

# Incorrect (absolute or wrong format)
- [Setup Guide](/docs/setup/setup-guide.md)
- [ADR 0001](setup-guide.md)
```

## 🔧 Maintenance

### Adding New Documentation

1. Create markdown file in appropriate subdirectory
2. Add entry to `docs/src/SUMMARY.md` in correct section
3. Use relative path: `../section/filename.md`
4. Run `mdbook build` to generate updated site

Example:
```markdown
# In docs/src/SUMMARY.md
## Tutorials
- [My New Tutorial](../tutorials/my-tutorial.md)
```

### Updating Existing Documentation

1. Edit markdown file directly
2. mdBook automatically picks up changes
3. Run `mdbook serve` to preview locally
4. Run `mdbook build` to generate static site

### Fixing Broken Links

mdBook will fail to build if referenced files don't exist. Check error output:

```
Error: Cannot find file '../nonexistent/file.md'
```

Verify the file exists and update the link path.

## 📦 Deployment

### Local Preview
```bash
mdbook serve
# Open http://localhost:3000
```

### GitHub Pages
```bash
mdbook build
git add docs/book/
git commit -m "docs: update mdBook"
git push origin main
```

Configure repository:
- Settings → Pages
- Source: `main` branch
- Path: `docs/book/`
- Custom domain: `docs.vapora.io` (optional)

### Docker (CI/CD)
```dockerfile
FROM rust:latest
RUN cargo install mdbook

WORKDIR /docs
COPY . .
RUN mdbook build

# Output: /docs/book/
```

### GitHub Actions
Add workflow file `.github/workflows/docs.yml`:

```yaml
name: Documentation Build

on:
  push:
    paths: ['docs/**']
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: peaceiris/actions-mdbook@v4
      - run: mdbook build
      - uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/book
```

## 🐛 Troubleshooting

| Problem | Solution |
|---------|----------|
| **Broken links in built site** | Use relative paths: `../file.md` not `/file.md` |
| **Search not working** | Rebuild with `mdbook build` |
| **Build fails silently** | Run `mdbook build` with `-v` flag for verbose output |
| **Theme not applying** | Remove `docs/book/` and rebuild |
| **Port 3000 in use** | Change port: `mdbook serve --port 3001` |
| **Missing file error** | Check file exists and update SUMMARY.md path |

## ✅ Verification

**Confirm successful setup:**

```bash
cd docs

# Build test
mdbook build
# Output: book/ directory created with 7.4 MB of files

# Check structure
ls -la book/index.html     # Should exist
ls -la src/SUMMARY.md      # Should exist
ls -la theme/vapora-custom.css  # Should exist

# Serve test
mdbook serve &
# Should output: Serving on http://0.0.0.0:3000
```

## 📚 Resources

- **mdBook Docs**: https://rust-lang.github.io/mdBook/
- **VAPORA Docs**: See `README.md` in this directory
- **Example**: Check `src/SUMMARY.md` for structure reference

## 📊 Statistics

| Metric | Value |
|--------|-------|
| **Documentation Files** | 75+ markdown files |
| **Indexed Entries** | 85+ in table of contents |
| **Build Output** | 7.4 MB (HTML + assets) |
| **Generated Pages** | 4 (index, print, TOC, 404) |
| **Build Time** | < 2 seconds |
| **Architecture Records** | 27 ADRs |
| **Integration Guides** | 5 guides |
| **Runbooks** | 8 operational guides |

---

**Setup Date**: 2026-01-12
**mdBook Version**: Latest (installed via `cargo install`)
**Status**: ✅ Fully Functional

For detailed mdBook usage, see `docs/README.md` in the repository.