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)

Code Blocks (MD031, MD040)
- Add blank line before and after fenced code blocks
- Always specify language: ```bash, ```rust, ```toml
- Use ```text for output/logs
Lists (MD032)
- Add blank line before and after lists
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

README.md

VAPORA Documentation

Quick Navigation

Documentation Structure