Skip to content

Installer et déployer MkDocs sur Debian 12

Objectif

Installer MkDocs et déployer un site statique via Apache2 sur un serveur Debian 12.

Prérequis

  • Serveur Debian 12.

  • Accès root ou sudo.

  • Accès Internet.

1. Préparer le serveur

Mettre à jour le système :

apt update
apt upgrade

Installer les paquets nécessaires :

apt install python3 python3-pip git apache2 -y

2. Installer MkDocs

Installer MkDocs avec pip :

pip install mkdocs --break-system-packages

Installer le thème Material (optionnel mais recommandé) :

pip install mkdocs-material --break-system-packages

Vérifier l'installation :

mkdocs --version

(Version conseillée : 1.6.1 en 2025)

3. Créer un projet MkDocs

Créer un nouveau projet :

mkdocs new mon-wiki

Se placer dans le dossier :

cd mon-wiki

Prévisualiser le site en local :

mkdocs serve

Accéder à :

http://IP:8000

(Ouvrir le port 8000 en TCP si nécessaire.)

4. Construire et déployer le site

Générer les fichiers statiques :

mkdocs build

Copier les fichiers vers Apache :

cp -r site/* /var/www/html/

Accéder à :

http://IP

5. Configurer Apache

Créer un VirtualHost :

nano /etc/apache2/sites-available/mkdocs.conf

Contenu :

<VirtualHost *:80>
    ServerName mon-site.com
    RedirectMatch ^/$ /accueil
    DocumentRoot /var/www/html

    <Directory /var/www/html>
        Options Indexes FollowSymLinks
        AllowOverride None
        Require all granted
    </Directory>

    ErrorDocument 404 /404.html

    ErrorLog ${APACHE_LOG_DIR}/error.log
    CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>

Adapter ServerName à votre IP ou domaine.

Activer la configuration :

ln -s /etc/apache2/sites-available/mkdocs.conf /etc/apache2/sites-enabled/

Désactiver le site par défaut :

rm /etc/apache2/sites-enabled/000-default.conf

Redémarrer Apache :

systemctl restart apache2

6. Automatiser la mise à jour du site

Créer un script de déploiement :

nano /usr/local/bin/mkdocs-update

Contenu du script :

#!/bin/bash
cd /home/CHEMIN || exit 1

echo "🚀 Génération du site MkDocs..."
mkdocs build

echo "📂 Copie des fichiers dans /var/www/html/"
cp -r /home/mkdox/spider/site/* /var/www/html/

echo "🔄 Changement des permissions..."
chown -R www-data:www-data /var/www/html/
chmod -R 755 /var/www/html/

echo "✅ Déploiement terminé !"

(Remplacer CHEMIN par le chemin absolu vers votre mkdocs.yml.)

Rendre le script exécutable :

chmod +x /usr/local/bin/mkdocs-update

Pour mettre à jour votre site :

mkdocs-update