MkDocs avec Material

Ce site est construit avec MKdocs, vous aussi vous voulez prendre des notes et documenter vos projets ? Trop facile !

Définitions

MkDocs

MkDocs est un générateur de sites de documentation statique, écrit en Python. Il est conçu pour être simple à utiliser et à configurer, tout en offrant de nombreuses fonctionnalités pour créer des sites de documentation attrayants et fonctionnels. MkDocs utilise des fichiers Markdown pour le contenu, ce qui permet aux utilisateurs de se concentrer sur l'écriture de la documentation sans se soucier de la mise en page.

MkDocs Material

MkDocs Material est un thème pour MkDocs qui utilise le framework Material Design de Google. Ce thème offre une interface utilisateur moderne et réactive, avec de nombreuses options de personnalisation. Il est particulièrement apprécié pour sa simplicité et son esthétique.

Fonctionnalités principales de MkDocs avec Material :

Simplicité d'utilisation : MkDocs est facile à installer et à configurer. Vous pouvez créer un site de documentation en quelques commandes.
Markdown : Utilise des fichiers Markdown pour le contenu, ce qui permet une écriture simple et lisible.
Personnalisation : Le thème Material offre de nombreuses options de personnalisation, y compris des palettes de couleurs, des icônes, et des extensions Markdown.
Recherche : Intègre une fonctionnalité de recherche pour permettre aux utilisateurs de trouver rapidement des informations.
Navigation : Offre une navigation intuitive avec des menus et des liens internes.
Extensions : Supporte de nombreuses extensions Markdown pour ajouter des fonctionnalités supplémentaires, comme les emojis, la coloration syntaxique, et les snippets de code.

Créer le site

1) Depuis votre machine locale, ouvrez votre terminal et tapez la commande suivante pour créer un environnement virtuel nommé mkdocs (ou ce que vous voulez) afin d'héberger votre contenu MkDocs :

python -m venv mkdocs

2) Activez l'environnement virtuel :

source mkdocs/bin/activate

Info

Ce n'est pas obligratoire mais créer un environnement virtuel Python permet d'isoler les dépendances de chaque projet, évitant ainsi les conflits de versions. Cela facilite la gestion des versions de Python et des bibliothèques, et améliore la portabilité et la sécurité des projets. Enfin, cela simplifie le développement et les tests en permettant de tester différentes configurations sans affecter l'installation globale de Python.

3) Créez un dossier qui contiendra votre répertoire de documentation (vos fichiers markdown et le fichier de configuration mkdocs.yml)

mkdir /chemin/vers/doc.mon_domaine.fr

Warning

Évitez de nommer votre dossier docs car c'est déjà le nom par défaut pour le répertoire MkDocs. Et choississez un répertoire sauvegardé !

4) Installez MkDocs et le thème MkDocs Material dans votre environnement virtuel :

pip install mkdocs

pip install mkdocs-material

5) Ouvrez le dossier de documentation que vous avez créé et entrez la commande suivante :

cd /chemin/vers/doc.mon_domaine.fr

mkdocs new .

Info

Cela créera un fichier YAML nommé mkdocs.yml, et un répertoire nommé docs contenant un fichier index.md à l'intérieur du répertoire de documentation doc.mon_domaine.fr :

docs est le répertoire où vous devrez déposer vos fichiers Markdown .md qui seront le contenu de votre site.
index.md est la page d'accueil de votre site.
mkdocs.yml est le fichier dans lequel vous aller configurer et personnaliser votre site.
L'architecture de votre dossier devrait ressembler à ceci :

doc.mon_domaine.fr
├─ docs/
│  └─ index.md
│  └─ Windows_Server.md
│  └─ Windows_Client.md
│  └─ Mes_notes_techniques.md
└─ mkdocs.yml

6) Modifiez votre fichier mkdocs.yml pour personnalier votre site. Voici celui que j'utilise avec mes commentaires pour comptendre chaques éléments :

Info

Référez vous à la documentation officielle https://squidfunk.github.io/mkdocs-material/reference

mkdocs.yml

site_name: De la doc comme elle vient !  # Nom du site
site_url: https://doc.glaztech.cloud  # URL du site

# Métadonnées de description <300 caractères, et d'auteur pour toutes les pages du site
site_description: Des cours, des ateliers et des notes techniques informatiques que j'ai écrits au fil de mes expériences, à votre libre disposition.
site_author: "Devrig DROUGLAZET"

theme:
  name: material  # Nom du thème utilisé
  font:
    text: Roboto # Google fonts téléchargée sur le serveur grâce au plugin Privacy pour conformité RGPD 
    code: Roboto Mono # Google fonts téléchargée sur le serveur grâce au plugin Privacy pour conformité RGPD 
  language: fr  # Langue du site (français)
  palette:
    # Palette toggle for automatic mode
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    # Palette toggle for light mode
    - media: "(prefers-color-scheme: light)"
      scheme: default
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    # Palette toggle for dark mode
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference
  features:
    - content.code.select  # Permet de sélectionner du code
    - content.code.copy  # Ajoute un bouton pour copier le code
    - navigation.top  # Ajoute un bouton pour revenir en haut de la page
    #- navigation.instant
    #- navigation.instant.prefetch

markdown_extensions:
  - abbr  # Abréviations
  - attr_list  # Listes d'attributs
  - meta  # Métadonnées
  - def_list  # Listes de définitions
  - pymdownx.emoji:  # Emojis
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
  - pymdownx.highlight:  # Coloration syntaxique
      anchor_linenums: true  # Ajoute des ancres pour les numéros de ligne
      line_spans: __span  # Utilise des spans pour les lignes
      pygments_lang_class: true  # Ajoute des classes de langage pour la coloration syntaxique
  - pymdownx.inlinehilite  # Coloration syntaxique en ligne
  - pymdownx.snippets  # Extraits de code
  - pymdownx.superfences  # Super clôtures pour le code
  - admonition  # Boîtes d'infos colorés (syntaxe Markdown : !!! info "Titre de l'info")
  - pymdownx.details  # Dérouler les admonitions

plugins:
  - privacy # The privacy plugin offers a streamlined solution for automatically self-hosting external assets. With just a single line of configuration, the plugin can automatically identify and download external assets, making GDPR compliance as effortless as it can possibly be.
  - search # The built-in search plugin integrates seamlessly with Material for MkDocs, adding multilingual client-side search with lunr and lunr-languages. It's enabled by default, but must be re-added to mkdocs.yml when other plugins are used.
  - search.suggest # When search suggestions are enabled, the search will display the likeliest completion for the last word
  - search.highlight # When search highlighting is enabled and a user clicks on a search result, Material for MkDocs will highlight all occurrences after following the link.
# Licence et information de droit d'auteur qui s'affiche dans le pied de page pour toutes les pages du site
copyright: >
    Contenus sous licence <a href="https://creativecommons.org/licenses/by-nc-sa/4.0/deed.fr" target="_blank">CC BY-NC-SA 4.0</a>

# Liens sociaux https://squidfunk.github.io/mkdocs-material/setup/setting-up-the-footer/#social-links
extra:
  social:
    - icon: fontawesome/brands/linkedin
      link: https://linkedin.com/in/devrigdrouglazet

Prévisualiser le site

Une fois que le contenu de votre site est prêt et configuré, vous pouvez le prévisualiser pour vous assurer que tout s'affiche correctement.

1) Servir le site en local :

cd /chemin/vers/doc.mon_domaine.fr

mkdocs serve

2) Copiez le lien localhost (http://127.0.0.1:8000/) qui s'affiche dans la sortie dans votre navigateur. Votre site web devrait s'afficher.

Info

Les modifications, suppression et ajouts de fichiers sont détectées automatiquement, il n'est pas nécessaire de relancer le serveur localhost.

3) Quittez le Terminal ou appuyez sur Ctrl +C pour arrêter le serveur localhost.

Créer le site

1) Exécutez la commande suivante dans votre terminal pour générer le contenu de votre dossier en un site web statique :

cd /chemin/vers/doc.mon_domaine.fr

mkdocs build

Info

Lorsque vous exécutez la commande mkdocs build, MkDocs traite vos fichiers Markdown et autres configurations spécifiées dans votre fichier mkdocs.yml et génère un site statique complet dans un répertoire nommé site par défaut, contenant les fichiers HTML, CSS et autres ressources.

Publiez le site en ligne

Vous pouvez pousser le contenu du répertoire site sur un dépot GitHub et le publier gratuitement sur GitHub Pages https://squidfunk.github.io/mkdocs-material/publishing-your-site/
Ou tout simplement, pousser le contenu vers votre propre site web Nginx, c'est ce que je fais!

Mon processus

Maintenant que mon site est en ligne et correctement configuré. Voici comment je procède.

Rédaction

J'écris sytématiquement mes notes en Markdown qui sont stockées dans un répertoire local et synchronisées dans mon cloud privé Nextcloud. J'y ai accès partout / tout le temps.

J'utilise Visual Studio Code pour la rédaction mais vous pouvez utiliser n'importe quel éditeur de texte (Obsidian, Notion, HackMD...) tant que vous respectez la syntaxe Markdown et renregistrez vos fichiers en .md

Automatisation

Ce script exécuté par crontab envoie les fichiers commencant par 1* vers le répertoire local MkDocs /chemin/vers/doc.mon_domaine.fr/docs puis se connecte à l'environnement virtuel Python du projet Mkdocs afin d'exécuter la commande mkdocs .build pour construire le site. Le contenu du dossier /chemin/vers/doc.mon_domaine.fr/site est synchronisé à l'identique via l'outils rclone vers mon serveur web en ligne, dans le répertoire qui contient les fichiers du site doc.mon_domaine.fr.

Cela me permet de ne pas me soucier de la mise à jour du site. J'ai juste à penser à mettre un "1" devant le nom du fichier .md si je veux qu'il soit en ligne.

#!/bin/bash

# Synchroniser les fichiers avec rsync des notes vers dossier local des Docs Mkdocs
rsync -av --include='1*' --include='index.md' --include='*.jpg' --include='*.jpeg' --include='*.png' --include='*.gif' --include='*.bmp' --exclude='*' --delete /chemin/vers/Notes/ /chemin/vers/doc.mon_domaine.fr/docs

# Activer l'environnement virtuel Python du projet MKDocs
source /home/dov/mkdocs/bin/activate

# Se positionner dans le répertoire local Mkdocs
cd '/chemin/vers/doc.mon_domaine.fr'

# Construire le site avec mkdocs
mkdocs build

# Quitter l'environnement virtuel Python du projet MKDocs
deactivate

# Synchroniser le site avec rclone
rclone sync /chemin/vers/doc.mon_domaine.fr/site/ serveur_web_remote:/var/www/doc.mon_domaine.fr/

Exemple Crontab pour exécution du script tous les jours à 10h.

0 10 * * * /home/utilisateur/chemin/vers/le/script/mkdocs_to_web.sh