# mdBook Source Directory

This directory contains the mdBook source files for VAPORA documentation.

## Contents

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

## How It Works

1. mdBook reads `SUMMARY.md` to build the navigation structure
2. All links in SUMMARY.md reference markdown files in parent `docs/` directory
3. Running `mdbook build` generates static HTML in `docs/book/`
4. 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:
```markdown
- [Getting Started](../getting-started.md)
- [Setup Guide](../setup/setup-guide.md)
```

## Building Documentation

From the `docs/` directory:

```bash
# Build static site
mdbook build

# Serve locally (with auto-reload)
mdbook serve

# Clean build output
mdbook clean
```

## Adding New Documentation

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

**Example:**

Add `docs/tutorials/my-tutorial.md`:

```markdown
# 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:
1. Edit theme files
2. Run `mdbook build --no-create-missing` to apply
3. Check `docs/book/` for output

---

**For full documentation**, see `../README.md`