# Documentation installation and setup

This guide covers how to set up the documentation build environment for the Wazuh Docker documentation.

## Prerequisites

The documentation is built using [mdBook](https://rust-lang.github.io/mdBook/), a command-line tool for creating books
with Markdown, along with [mdBook Mermaid](https://github.com/badboy/mdbook-mermaid) for diagram support.

## Required versions

- **mdbook**: 0.5.2
- **mdbook-mermaid**: 0.17.0

## Installation

Install tools:

```bash
cargo install mdbook --version 0.5.2
cargo install mdbook-mermaid --version 0.17.0
``

Verify installation:

```bash
mdbook --version
mdbook-mermaid --version
```

## Building the documentation

Once you have installed mdBook and mdBook Mermaid:

```bash
# Navigate to the docs directory
cd docs

# Build the documentation (generates html in docs/book/)
mdbook build

# Serve locally with live reload (recommended for development)
mdbook serve --open
```

The documentation will be available at `http://localhost:3000` when using `mdbook serve`.

## Development workflow

When editing documentation:

1. Run `mdbook serve --open` from the `docs/` directory
2. Edit markdown files in `docs/ref/`
3. Changes are automatically reflected in the browser
4. Navigation structure is defined in `docs/SUMMARY.md`

## Troubleshooting

### Version mismatch errors

If you encounter build errors, verify you have the correct versions installed:

```bash
mdbook --version
mdbook-mermaid --version
```

If you have different versions, uninstall the current ones and reinstall by following the [Installation section](#installation):

```bash
cargo uninstall mdbook
cargo uninstall mdbook-mermaid
```

### Cargo install fails with feature 'edition2024' is required

You may see an error like:

```sh
failed to download `globset v0.4.18`
failed to parse manifest ... feature `edition2024` is required
The package requires the Cargo feature called `edition2024`, but that feature is not stabilized in this version of Cargo.
```

This happens because one of mdBook's transitive dependencies has been updated to use Rust edition 2024, which is only
supported on nightly Rust toolchains.

To fix it install using nightly Rust:

```sh
rustup install nightly
rustup run nightly cargo install mdbook --version 0.4.52
```

### Mermaid diagrams not rendering

If Mermaid diagrams are not rendering in the browser:

1. Clear your browser cache
2. Run `mdbook clean` to remove the build directory
3. Run `mdbook serve --open` again

### Port already in use

If port 3000 is already in use, specify a different port:

```bash
mdbook serve --port 3001 --open
```

## Additional resources

- [mdBook documentation](https://rust-lang.github.io/mdBook/)
- [mdBook Mermaid documentation](https://github.com/badboy/mdbook-mermaid)
- [Mermaid diagram syntax](https://mermaid.js.org/)