fk-wazuh/docs/INSTALLATION.md

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, a command-line tool for creating books with Markdown, along with mdBook Mermaid for diagram support.

Required versions

• mdbook: 0.5.2
• mdbook-mermaid: 0.17.0

Installation

Install tools:

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

Verify installation:

mdbook --version
mdbook-mermaid --version

Building the documentation

Once you have installed mdBook and mdBook Mermaid:

# 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:

mdbook --version
mdbook-mermaid --version

If you have different versions, uninstall the current ones and reinstall by following the Installation section:

cargo uninstall mdbook
cargo uninstall mdbook-mermaid

Cargo install fails with feature 'edition2024' is required

You may see an error like:

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 can happen when installing mdbook version 0.5.2 because one of its transitive dependencies has been updated to use Rust edition 2024, which is only supported on nightly Rust toolchains.

To fix it, install the required mdbook version (0.5.2) using nightly Rust:

rustup install nightly
rustup run nightly cargo install mdbook --version 0.5.2

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:

mdbook serve --port 3001 --open

Additional resources

• mdBook documentation
• mdBook Mermaid documentation
• Mermaid diagram syntax