mdBook Source Directory

This directory contains the mdBook source files for VAPORA documentation.

SUMMARY.md — Table of contents that mdBook uses to generate navigation
intro.md — Landing/introduction page for the documentation site

How It Works

mdBook reads SUMMARY.md to build the navigation structure
All links in SUMMARY.md reference markdown files in parent docs/ directory
Running mdbook build generates static HTML in docs/book/
Running mdbook serve starts a local development server

File Organization

src/
├── SUMMARY.md    (navigation index)
└── intro.md      (landing page)

../              (actual documentation files)
├── README.md
├── getting-started.md
├── setup/
├── architecture/
├── adrs/
└── ...

Relative Path Pattern

All links in this directory use relative paths to reference docs:

Same level: ../file.md
Subdirectory: ../folder/file.md
Parent level: ../../file.md

Example from SUMMARY.md:

- [Getting Started](../getting-started.md)
- [Setup Guide](../setup/setup-guide.md)

Building Documentation

From the docs/ directory:

# Build static site
mdbook build

# Serve locally (with auto-reload)
mdbook serve

# Clean build output
mdbook clean

Adding New Documentation

Create markdown file in appropriate docs/ subdirectory
Add entry to src/SUMMARY.md in the correct section
Use relative paths: ../section/filename.md
Run mdbook build to generate updated site

Example:

Add docs/tutorials/my-tutorial.md:

# In docs/src/SUMMARY.md

## Tutorials
- [My Tutorial](../tutorials/my-tutorial.md)

Theme Customization

Custom theme files located in docs/theme/:

index.hbs — HTML template
vapora-custom.css — Custom styles

To modify:

Edit theme files
Run mdbook build --no-create-missing to apply
Check docs/book/ for output

For full documentation, see ../README.md

2.0 KiB Raw Blame History