Skip to content

MkDocs Material - Documentation

MkDocs Material est utilisé pour générer et servir la documentation du serveur. Le site est hébergé dans un conteneur Docker dans le LXC 101 (Management).

Informations de service

  • Conteneur : docs
  • Image : squidfunk/mkdocs-material:latest
  • Port : 8001 → 8000 (interne)
  • URL : http://192.168.1.12:8001
  • Volume : /mnt/documentation (LXC) ← /mnt/lxc-data/documentation (Proxmox)
  • Fichier compose : /opt/docker/docker-compose.yaml

Configuration

Docker Compose

documentation:
  image: squidfunk/mkdocs-material:latest
  container_name: docs
  volumes:
    - /mnt/documentation:/docs
  ports:
    - 8001:8000
  restart: unless-stopped
  environment:
    - PYTHONUNBUFFERED=1
    - WATCHFILES_FORCE_POLLING=true
  command: serve --dev-addr=0.0.0.0:8000 --livereload

Structure

/mnt/lxc-data/documentation/
├── mkdocs.yml              # Configuration MkDocs
├── docs/                   # Fichiers Markdown
│   ├── index.md
│   ├── applications/
│   ├── infrastructure/
│   ├── services/
│   └── ...
└── site/                   # Site généré (build)

Problème : Auto-reload cassé

Symptômes

Après une mise à jour de l'image Docker mkdocs-material vers la version ≥9.6.21, le rechargement automatique (live-reload) ne fonctionnait plus :

  • Le serveur démarre correctement
  • Le site est accessible
  • Mais : les modifications des fichiers Markdown ne sont pas détectées
  • Le site ne se reconstruit pas automatiquement
  • Le navigateur ne se recharge pas

Logs caractéristiques

Version cassée (≥9.6.21) :

INFO    -  Building documentation...
INFO    -  Documentation built in 2.10 seconds
INFO    -  [23:03:08] Serving on http://0.0.0.0:8000/

Version fonctionnelle (<9.6.21) :

INFO    -  Building documentation...
INFO    -  Documentation built in 2.23 seconds
INFO    -  [23:01:41] Watching paths for changes: 'docs', 'mkdocs.yml', '.'
INFO    -  [23:01:41] Serving on http://0.0.0.0:8000/

La ligne "Watching paths for changes" est absente dans la version cassée.

Cause racine

Ce problème est dû à un bug dans Click 8.3.0, une bibliothèque Python dont dépend MkDocs pour gérer les arguments en ligne de commande.

  • Issue GitHub : squidfunk/mkdocs-material#8478
  • Bibliothèque affectée : Click 8.3.0
  • Versions impactées : mkdocs-material ≥9.6.21
  • Statut MkDocs : Projet actuellement non maintenu, fix non prévu à court terme

Le problème n'est pas lié à :

  • ❌ Docker bind mounts
  • ❌ Proxmox LXC
  • ❌ Système de fichiers
  • ❌ Permissions
  • ❌ inotify

Solution appliquée

La solution officielle recommandée est d'ajouter le flag --livereload explicitement dans la commande mkdocs serve.

Commandes utiles

Gestion du service

# Redémarrer le conteneur
pct exec 101 -- docker restart docs

# Via docker-compose
pct exec 101 -- bash -c "cd /opt/docker && docker compose restart documentation"

# Arrêter/démarrer
pct exec 101 -- bash -c "cd /opt/docker && docker compose down documentation"
pct exec 101 -- bash -c "cd /opt/docker && docker compose up -d documentation"

Logs et débogage

# Logs en temps réel
pct exec 101 -- docker logs -f docs

# Dernières 50 lignes
pct exec 101 -- docker logs --tail 50 docs

# Logs depuis 5 minutes
pct exec 101 -- docker logs --since 5m docs

# Vérifier le statut
pct exec 101 -- docker ps --filter name=docs

Build manuel

# Build du site statique
pct exec 101 -- docker exec docs mkdocs build

# Avec mode strict (erreurs sur warnings)
pct exec 101 -- docker exec docs mkdocs build --strict

# Nettoyer le site
pct exec 101 -- docker exec docs mkdocs build --clean

Accès au conteneur

# Shell dans le conteneur
pct exec 101 -- docker exec -it docs /bin/bash

# Vérifier la config
pct exec 101 -- docker exec docs cat /docs/mkdocs.yml

# Lister les fichiers
pct exec 101 -- docker exec docs ls -la /docs/

Résolution de problèmes

Le site ne charge pas

Vérifier le conteneur :

pct exec 101 -- docker ps --filter name=docs
pct exec 101 -- docker logs --tail 30 docs

Vérifier le port :

pct exec 101 -- netstat -tuln | grep 8001
curl http://192.168.1.12:8001

Erreurs de build

Liens cassés : Vérifier les liens relatifs dans les fichiers Markdown

# Chercher les warnings dans les logs
pct exec 101 -- docker logs docs | grep WARNING

Fichiers manquants : Vérifier le montage du volume

pct exec 101 -- ls -la /mnt/documentation/docs/

Auto-reload ne fonctionne toujours pas

  1. Vérifier le flag --livereload :
pct exec 101 -- docker inspect docs --format '{{.Config.Cmd}}'
  1. Vérifier les logs pour "Watching paths" :
pct exec 101 -- docker logs docs | grep -i watch
  1. Test manuel :
echo "test" >> /mnt/lxc-data/documentation/docs/index.md
sleep 3
pct exec 101 -- docker logs --tail 10 docs
  1. Si toujours cassé, envisager le script inotify externe

Maintenance

Mise à jour de l'image

# Dans le LXC 101
cd /opt/docker
docker compose pull documentation
docker compose up -d documentation

# Vérifier les logs
docker logs --tail 50 docs

Sauvegarde

Les fichiers sources sont déjà sauvegardés via le système de backup Proxmox (LXC bind mount).

Le site généré (site/) n'est pas critique car il peut être régénéré :

mkdocs build

Références