94 lines
2 KiB
Markdown
94 lines
2 KiB
Markdown
# 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`
|