Vapora/docs/README.md

VAPORA Documentation

Complete user-facing documentation for VAPORA, an intelligent development orchestration platform.

Quick Navigation

• Getting Started — Start here
• Quickstart — Quick setup guide
• Setup & Deployment — Installation, configuration, deployment
• Features — Capabilities and overview
• Architecture — Design, planning, and system overview
• Integrations — Integration guides and APIs
• Branding — Brand assets and guidelines
• Executive Summary — Executive-level summaries

Documentation Structure

docs/
├── README.md                    (this file - directory index)
├── getting-started.md           (entry point)
├── quickstart.md                (quick setup)
├── branding.md                  (brand guidelines)
├── setup/                       (installation & deployment)
│   ├── README.md
│   ├── setup-guide.md
│   ├── deployment.md
│   ├── tracking-setup.md
│   └── ...
├── features/                    (product capabilities)
│   ├── README.md
│   └── overview.md
├── architecture/                (design & planning)
│   ├── README.md
│   ├── project-plan.md
│   ├── phase1-integration.md
│   ├── completion-report.md
│   └── ...
├── integrations/                (integration guides)
│   ├── README.md
│   ├── doc-lifecycle.md
│   └── ...
└── executive/                   (executive summaries)
    ├── README.md
    ├── executive-summary.md
    └── resumen-ejecutivo.md

mdBook Integration

Overview

This documentation project is fully integrated with mdBook, a command-line tool for building books from markdown. All markdown files in this directory are automatically indexed and linked through the mdBook system.

Directory Structure for mdBook

docs/
├── book.toml                        (mdBook configuration)
├── src/
│   ├── SUMMARY.md                   (table of contents - auto-generated)
│   ├── intro.md                     (landing page)
├── theme/                           (custom styling)
│   ├── index.hbs                    (HTML template)
│   └── vapora-custom.css            (custom CSS theme)
├── book/                            (generated output - .gitignored)
│   └── index.html
├── .gitignore                       (excludes build artifacts)
│
├── README.md                        (this file)
├── getting-started.md               (entry points)
├── quickstart.md
├── examples-guide.md                (examples documentation)
├── tutorials/                       (learning tutorials)
│
├── setup/                           (installation & deployment)
├── features/                        (product capabilities)
├── architecture/                    (system design)
├── adrs/                            (architecture decision records)
├── integrations/                    (integration guides)
├── operations/                      (runbooks & procedures)
└── disaster-recovery/               (recovery procedures)

Building the Documentation

Install mdBook (if not already installed):

cargo install mdbook

Build the static site:

cd docs
mdbook build

Output will be in docs/book/ directory.

Serve locally for development:

cd docs
mdbook serve

Then open http://localhost:3000 in your browser. Changes to markdown files will automatically rebuild.

Documentation Guidelines

File Naming

• Root markdown: UPPERCASE (README.md, CHANGELOG.md)
• Content markdown: lowercase (getting-started.md, setup-guide.md)
• Multi-word files: kebab-case (setup-guide.md, disaster-recovery.md)

Structure Requirements

• Each subdirectory must have a README.md
• Use relative paths for internal links: [link](../other-file.md)
• Add proper heading hierarchy: Start with h2 (##) in content files

Markdown Compliance (markdownlint)

1. Code Blocks (MD031, MD040)

   • Add blank line before and after fenced code blocks
   • Always specify language: ```bash, ```rust, ```toml
   • Use ```text for output/logs

2. Lists (MD032)

   • Add blank line before and after lists

3. Headings (MD022, MD001, MD026, MD024)

   • Add blank line before and after headings
   • Heading levels increment by one
   • No trailing punctuation
   • No duplicate heading names

mdBook Configuration (book.toml)

Key settings:

[book]
title = "VAPORA Platform Documentation"
src = "src"                    # Where mdBook reads SUMMARY.md
build-dir = "book"             # Where output is generated

[output.html]
theme = "theme"                # Path to custom theme
default-theme = "light"
edit-url-template = "https://github.com/.../edit/main/docs/{path}"

Custom Theme

Location: docs/theme/

• index.hbs — HTML template
• vapora-custom.css — Custom styling with VAPORA branding

Features:

• Professional blue/violet color scheme
• Responsive design (mobile-friendly)
• Dark mode support
• Custom syntax highlighting
• Print-friendly styles

Content Organization

The src/SUMMARY.md file automatically indexes all documentation:

# VAPORA Documentation

## [Introduction](../README.md)

## Getting Started
- [Quick Start](../getting-started.md)
- [Quickstart Guide](../quickstart.md)

## Setup & Deployment
- [Setup Overview](../setup/README.md)
- [Setup Guide](../setup/setup-guide.md)
...

No manual updates needed — SUMMARY.md structure remains constant as new docs are added to existing sections.

Deployment

GitHub Pages:

# Build the book
mdbook build

# Commit and push
git add docs/book/
git commit -m "chore: update documentation"
git push origin main

Configure GitHub repository settings:

• Source: main branch
• Path: docs/book/
• Custom domain: docs.vapora.io (optional)

Docker (for CI/CD):

FROM rust:latest
RUN cargo install mdbook

WORKDIR /docs
COPY . .
RUN mdbook build

# Output in /docs/book/

Troubleshooting

Issue	Solution
Links broken in mdBook	Use relative paths: ../file.md not file.md
Theme not applying	Ensure theme/ directory exists, run mdbook build --no-create-missing
Search not working	Rebuild with mdbook build
Build fails	Check for invalid TOML in book.toml

Quality Assurance

Before committing documentation:

# Lint markdown
markdownlint docs/**/*.md

# Build locally
cd docs && mdbook build

# Verify structure
cd docs && mdbook serve
# Open http://localhost:3000 and verify navigation

CI/CD Integration

Add to .github/workflows/docs.yml:

name: Documentation

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

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

---

Content Standards

Ensure all documents follow:

• Lowercase filenames (except README.md)
• Kebab-case for multi-word files
• Each subdirectory has README.md
• Proper heading hierarchy
• Clear, concise language
• Code examples when applicable
• Cross-references to related docs