Bonnes pratiques et cas avances¶

Ce chapitre couvre les sujets avances pour opérer la plateforme de documentation en production : haute disponibilité, optimisation des performances, migration depuis d'autres outils, gestion multilingue, conventions pour les assets et résolution de problèmes courants.

Haute disponibilité¶

MkDocs produit des fichiers statiques — HTML, CSS, JS, images. Toute stratégie HA standard pour un serveur de fichiers statiques s'applique sans adaptation particulière. Il n'y a pas d'état applicatif a synchroniser entre les replicas.

Pour une documentation interne classifiee, deux replicas Caddy derriere un load balancer suffisent. Le build CI pousse les fichiers vers un volume NFS partage monte par les deux instances.

# Caddyfile du load balancer
docs.example.com {
    reverse_proxy caddy-1:80 caddy-2:80 {
        lb_policy round_robin
        health_uri /
        health_interval 10s
    }
}

Performance et optimisation¶

Minification HTML¶

Le plugin mkdocs-minify reduit la taille des pages HTML a la compilation sans modifier le rendu.

# mkdocs.yml
plugins:
  - search
  - minify:
      minify_html: true
      minify_js: true
      minify_css: true
      htmlmin_opts:
        remove_comments: true

Cache CI et compression¶

Mettre en cache le virtualenv Python entre les executions CI divise le temps de build par deux en moyenne. Dans GitLab CI :

build-docs:
  cache:
    key: docs-venv-$CI_COMMIT_REF_SLUG
    paths:
      - .venv/

Activer la compression et les en-têtes de cache navigateur dans Caddy :

docs.example.com {
    encode { br; gzip 6 }
    root * /srv/docs
    file_server

    @assets { path *.css *.js *.png *.svg *.woff2 }
    header @assets Cache-Control "public, max-age=31536000, immutable"
    header *.html Cache-Control "no-cache, must-revalidate"
}

Pre-rendu de l'index de recherche¶

MkDocs Material pre-calcule l'index Lunr au moment du build. Pour les sites volumineux (> 500 pages), limiter la profondeur d'indexation reduit la taille de l'index :

plugins:
  - search:
      lang: fr
      indexing: 'titles'  # 'full' par defaut

Migration de contenu¶

Depuis Confluence¶

Confluence exporte le contenu en HTML via "Space Export". Pandoc convertit ce HTML en Markdown.

#!/bin/bash
# confluence-to-md.sh — prerequis : pandoc >= 3.0
INPUT_DIR="./confluence-export/html"
OUTPUT_DIR="./docs/migrated"
mkdir -p "${OUTPUT_DIR}"

find "${INPUT_DIR}" -name "*.html" | while read -r html_file; do
  base=$(basename "${html_file}" .html)
  out="${OUTPUT_DIR}/${base}.md"
  pandoc --from html --to markdown+pipe_tables+fenced_code_blocks \
    --wrap=none --output "${out}" "${html_file}"
  # Prepend front matter
  printf -- '---\ntitle: "%s"\nclassification: internal\n---\n\n' "${base}" \
    | cat - "${out}" > "${out}.tmp" && mv "${out}.tmp" "${out}"
done

Depuis Wiki.js¶

Wiki.js dispose d'un export natif en Markdown (Administration > Storage > Export). La structure exportee est généralement plate ; reorganisez les fichiers pour correspondre a l'arborescence MkDocs cible.

Depuis un wiki interne generique¶

1. Exporter le contenu dans le format le plus proche du Markdown disponible.
2. Utiliser Pandoc pour la conversion (HTML, RST, DOCX).
3. Passer markdownlint pour corriger les artefacts de conversion.
4. Reclasser les pages selon le plan de navigation MkDocs.
5. Vérifier les liens internes — ils changent systematiquement lors d'une reorganisation.

Multi-langue¶

Le plugin mkdocs-i18n gère des sites multilingues avec une structure de fichiers dédiée par langue.

# mkdocs.yml
plugins:
  - i18n:
      default_language: fr
      languages:
        fr: { name: Francais, build: true }
        en: { name: English, build: true }

Structure recommandee :

docs/
  index.md              # Langue par defaut (fr)
  index.en.md           # Version anglaise
  tutorials/
    services/
      documentation/
        01-fondamentaux.md
        01-fondamentaux.en.md

Le champ classification du front matter est indépendant de la langue. Une page confidentielle et sa traduction doivent toutes deux porter la même valeur. Le plugin de filtrage opère avant la génération de la navigation quelle que soit la langue active.

Gestion des assets¶

Les images et fichiers attaches a une page classifiee doivent etre places dans un sous-répertoire images/ au même niveau que la page, pas dans un répertoire partage global.

docs/
  tutorials/
    services/
      documentation/
        images/
          architecture-confidentielle.png   # asset classe
        03-architecture.md

Granularité infra-page¶

Le filtre de classification opère au niveau de la page entière, pas au niveau d'une section. Il n'est pas possible de masquer un seul paragraphe dans une page visible par tous.

Si une page contient des sections de niveaux différents, divisez-la en deux fichiers distincts :

# Avant (problematique)
guide-deploiement.md   # classification: internal
  ## Etapes publiques
  ## Cles et secrets    <-- devrait etre restricted

# Apres (recommande)
guide-deploiement.md             # classification: internal
guide-deploiement-secrets.md     # classification: restricted

Troubleshooting¶

# Verifier les classifications presentes dans le depot
grep -r "^classification:" docs/ | sort | uniq -c | sort -rn

# Lister toutes les pages d'une classification donnee
grep -rl "^classification: restricted" docs/