feat: migrate mkdocs to mdbook (#130)

* chore: migrate documentation from MkDocs to mdBook

- Remove MkDocs config files (mkdocs.yml, includes.yml, theme_overrides/)
- Add mdBook build config (book.toml)
- Add Cosmian/doc-theme as git submodule (documentation/theme)
- Update README rendering sections to mdBook

* fix(audit): ignore RUSTSEC-2026-0194 and 0195 (quick-xml, blocked on cosmian_kmip)

* docs: add nav.yml for standalone mdBook builds

* ci: merge doc wf into build.yml

* fix: mdbook build

* fix: deny advisories and doc build

- deny.toml: ignore RUSTSEC-2026-0173/0194/0195 (no upgrades available)
- documentation/book.toml: use src = docs (tracked dir, was pointing to gitignored src/)

* fix: documentation build in CI

- main_base.yml: add submodules: recursive to build-documentation checkout
  (theme submodule contains required CSS/JS and scripts)
- book.toml: remove unused [preprocessor.tabs] (no docs use tab syntax,
  and the path was wrong - pointed outside the repo)

* fix: mdbook build

* fix: reenable TOC and fix Markdown lints

* fix: replace Cosmian by Eviden everywhere

* fix: fix build and linkcheck issues

* fix:fix

---------

Co-authored-by: HatemMn <19950216+HatemMn@users.noreply.github.com>

Author: Manuthor

.cargo/audit.toml

@@ -6,4 +6,6 @@
 ignore = [
     "RUSTSEC-2023-0071", # rsa
     "RUSTSEC-2024-0436", # unmaintained paste
+    "RUSTSEC-2026-0194", # quick-xml: quadratic runtime on duplicate attrs — fixed in >=0.41.0; blocked on cosmian_kmip upgrade
+    "RUSTSEC-2026-0195", # quick-xml: unbounded NS-decl allocation DoS — fixed in >=0.41.0; blocked on cosmian_kmip upgrade
 ]

.github/workflows/main_base.yml

@@ -98,3 +98,19 @@ jobs:
           repo: Cosmian/public_documentation
           ref: main
           token: ${{ secrets.PAT_TOKEN }}
+
+  build-documentation:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+
+      - name: Install mdBook toolchain
+        run: curl -fsSL https://raw.githubusercontent.com/Cosmian/doc-theme/main/scripts/setup-mdbook.sh | sh
+
+      - name: Build documentation
+        run: |
+          export PATH="$HOME/.cargo/bin:$PATH"
+          cd documentation && mdbook build

.gitmodules

@@ -5,3 +5,6 @@
 [submodule "test_data"]
 	path = test_data
 	url = https://github.com/Cosmian/test_data.git
+[submodule "documentation/theme"]
+	path = documentation/theme
+	url = git@github.com:Cosmian/doc-theme.git

.markdownlint.yaml

@@ -11,3 +11,7 @@ MD007:
 MD024:
   # Allow heading duplication if under different parent headings
   siblings_only: true
+
+# Heading structure requirements (see also kms/.github/.markdownlint.yaml for consistency)
+MD041: true # First heading in a file must be a top-level heading (#)
+MD025: true # Only one top-level heading (#) per file

.pre-commit-config.yaml

@@ -34,7 +34,10 @@ repos:
     rev: v0.44.0
     hooks:
       - id: markdownlint-fix
-        args: [--disable=MD013, --disable=MD041, --disable=MD046, --fix]
+        args: [--disable=MD013, --disable=MD046, --fix]
+        # MD041 (first heading must be #) and MD025 (only one # per file) are intentionally enabled
+        # SUMMARY.md uses empty links for mdBook section separators (valid mdBook syntax)
+        exclude: documentation/docs/SUMMARY\.md
 
   - repo: https://github.com/tcort/markdown-link-check
     rev: v3.13.7