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)

cargo install mdbook

Build the documentation

cd docs
mdbook build

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

Serve locally for development

cd docs
mdbook serve

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

Changes to markdown files will automatically rebuild the documentation.

Clean build output

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

# 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:

# 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

mdbook serve
# Open http://localhost:3000

GitHub Pages

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)

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:

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:

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.