Installer MkDocs avec pip

Pré-requis : Assurez-vous que Python et pip sont installés sur votre serveur.
Exécutez pip install mkdocs pour installer MkDocs. Installez ensuite Material for MkDocs avec pip install mkdocs-material.

Créer un nouveau répertoire pour la documentation

Créez un répertoire séparé pour votre documentation, par exemple, /var/www/docs.
Initialisez un nouveau projet MkDocs dans ce répertoire avec la commande mkdocs new /var/www/docs.

Configurer MkDocs

Dans le répertoire /var/www/docs, éditez le fichier mkdocs.yml pour configurer votre site de documentation.
Définissez le thème sur Material en ajoutant la ligne theme: material dans le fichier mkdocs.yml.

Générer le site de documentation

Dans votre répertoire de documentation, exécutez mkdocs build. Cela générera le site statique dans le sous-répertoire site.

Configurer Apache pour servir la documentation

Vous devez configurer un VirtualHost ou un Alias dans votre configuration Apache pour pointer vers le répertoire généré par MkDocs.
Si vous utilisez un Alias, ajoutez quelque chose comme Alias /docs /var/www/docs/site dans votre configuration Apache. Cela permettra d'accéder à la documentation via http://votre-domaine.com/docs.

Exemple d'hôte virtuel Apache

Exemple de fichier de configuration pour Apache2 nommé mkdocs.conf dans /etc/apache2/sites-available/mkdocs.conf :

<VirtualHost *:443>
 ServerName mkdocs.votre-domain.com
 DocumentRoot /var/www/docs/site

SSLEngine on
 SSLCertificateFile /etc/letsencrypt/live/votre-domain.com/fullchain.pem
 SSLCertificateKeyFile /etc/letsencrypt/live/votre-domain.com/privkey.pem
 Include /etc/letsencrypt/options-ssl-apache.conf

ErrorLog ${APACHE_LOG_DIR}/mkdocs_error.log
 CustomLog ${APACHE_LOG_DIR}/mkdocs_access.log combined

<Directory /var/www/docs/site>
 AllowOverride All
 Require all granted
 </Directory>
</VirtualHost>

Activer le nouvel hôte virtuel : a2ensite mkdocs.conf
Après avoir modifié la configuration, redémarrez Apache pour appliquer les changements avec sudo systemctl restart apache2.

Mises à jour du site

Pour mettre à jour la documentation, vous pouvez simplement modifier les fichiers dans /var/www/docs, exécuter mkdocs build à nouveau, et le site de documentation sera mis à jour.

Création d'une entrée DNS

La dernière étape pour permettre l'accès à ce site consiste à créer une entrée de type A dans la zone DNS du domaine concerné.