Merge pull request #2264 from wazuh/change/4323-update-devops-repositories-docs-config-and-tooling-versions-to-meet-new-standards

Updated wazuh-docker documentation config and tooling versions to meet new standards

.gitignore

@@ -11,3 +11,6 @@ multi-node/wazuh-certificates/*
 multi-node/wazuh-certificates-tool.log
 multi-node/wazuh-certs-tool*.sh
 multi-node/config*.yml
+
+# Documentation
+docs/book/

CHANGELOG.md

@@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 
+- Updated wazuh-docker documentation config and tooling versions to meet new standards. ([#2264](https://github.com/wazuh/wazuh-docker/pull/2264))
 - Update certificate configuration to use separate IP and DNS fields ([#2253](https://github.com/wazuh/wazuh-docker/pull/2253))
 - Modify Healthchecks ([#2252](https://github.com/wazuh/wazuh-docker/pull/2252))
 - Add deployment healthchecks ([#2251](https://github.com/wazuh/wazuh-docker/pull/2251))

docs/INSTALLATION.md

@@ -0,0 +1,115 @@
+# 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 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:
+
+```sh
+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:
+
+```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/)

docs/book.toml

@@ -1,6 +1,31 @@
 [book]
-title = "Wazuh Docker Documentation"
+title = "Wazuh Docker documentation"
-description = "Technical documentation for Wazuh Docker deployment."
+authors = ["Wazuh XDRSIEM DevOps Team"]
-authors = ["Victor Erenu"]
+description = "The technical documentation for the Wazuh Docker deployment."
+language = "en"
 src = "."
-language = "en"
+
+[build]
+build-dir = "book"
+create-missing = false
+
+[preprocessor.mermaid]
+command = "mdbook-mermaid"
+
+[output.html]
+default-theme = "light"
+preferred-dark-theme = "navy"
+git-repository-url = "https://github.com/wazuh/wazuh-docker"
+additional-js = ["mermaid.min.js", "mermaid-init.js"]
+
+[output.html.fold]
+enable = true
+level = 0
+
+[output.html.search]
+enable = true
+
+[output.html.playground]
+editable = false
+copyable = true
+

docs/mermaid-init.js

@@ -0,0 +1,35 @@
+(() => {
+    const darkThemes = ['ayu', 'navy', 'coal'];
+    const lightThemes = ['light', 'rust'];
+
+    const classList = document.getElementsByTagName('html')[0].classList;
+
+    let lastThemeWasLight = true;
+    for (const cssClass of classList) {
+        if (darkThemes.includes(cssClass)) {
+            lastThemeWasLight = false;
+            break;
+        }
+    }
+
+    const theme = lastThemeWasLight ? 'default' : 'dark';
+    mermaid.initialize({ startOnLoad: true, theme });
+
+    // Simplest way to make mermaid re-render the diagrams in the new theme is via refreshing the page
+
+    for (const darkTheme of darkThemes) {
+        document.getElementById(darkTheme).addEventListener('click', () => {
+            if (lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+
+    for (const lightTheme of lightThemes) {
+        document.getElementById(lightTheme).addEventListener('click', () => {
+            if (!lastThemeWasLight) {
+                window.location.reload();
+            }
+        });
+    }
+})();