MkDocs (Générateur de documentation)

Logo MkDocs

Environnement

  • Ubuntu 18.04

Installation

  • Créer un utilisateur user :
useradd -m user 
passwd user

  • Configurer l'accès SSH à clé privée

  • Installer pip :

apt install python3-pip
  • Installer mkdocs et les thèmes ReadTheDocs-DropDown et WindMill (/!\ avec un compte utilisateur) :
pip3 install mkdocs
pip3 install mkdocs-windmill
pip3 install mkdocs-ivory
pip3 install rtd-dropdown
pip3 install mkdocs-terminal
  • Corriger le problème de mise en page du thème ReadTheDocs-DropDown modifiant la ligne 75 (white-space:) du fichier /home/user/.local/lib/python3.10/site-packages/rtd_dropdown/css/theme_extra.css comme suit : 
nano /home/user/.local/lib/python3.10/site-packages/rtd_dropdown/css/theme_extra.css

pre code {
  white-space: pre !important;
  word-wrap: normal;
  display: block;
  padding: 12px;
  font-size: 1px;
}

Utilisation

  • Créer un nouveau projet : 
cd /home/user
/home/user/.local/bin/mkdocs new mon_projet
  • Démarrer le serveur : 
cd mon_projet
/home/user/.local/bin/mkdocs serve --dev-addr 0.0.0.0:8000 -t v
  • Construire le site statique : 
/home/user/.local/bin/mkdocs build -t rtd-dropdown

Exporter le site vers le serveur Web

  • Sauvegarder l'ancien site :
ssh root@ip_serveur_web

mv /var/www/web_site /var/www/web_site.old

mkdir /var/www/web_site
  • Copier les fichiers vers le nouveau dossier :
scp -pr /home/user/mon_projet/site/* root@ip_serveur_web:/var/www/web_site
  • Modifier les propriétaires des fichiers : 
chown -R www-data:www-data /var/www/web_site

Sources

https://www.mkdocs.org/#installation