Découverte de Mkdocs

Je viens de découvrir le projet MkDocs. Cela permet de transformer des fichiers Markdown en sites web statiques. On peut aussi le personnaliser avec des thèmes et des plugins.

J'ai voulu réaliser un POC (Proof of Concept) et finalement, je me suis dit que c'était l'occasion de faire un site pour partager mes différentes procédures et mes retours d'expérience sur des POC que je fais au quotidien.

Ainsi, voici mon premier article sur comment faire ce même site avec MkDocs.

Installer MkDocs

Je vous conseille toujours de faire un venv python.

Cette procédure a été réalisée sur un OS Linux (Pop!_OS 22.04).

Installer le paquet python mkdocs

pip3 install mkdocs

Il semble que dans notre cas, il y a un problème de PATH

[ Facultatif ] Debug probleme de PATH

*Cela peut être réparé en ajoutant au PATH le dossier *

export PATH="$HOME/.local/bin:$PATH"

Création du projet blog et le démarre en localhost

Configure MkDocs et démarre un serveur qui sert le site en local. Pratique pour tester, car ça s'actualise automatiquement.

mkdocs new blog
cd blog/
mkdocs serve

Je dépose un fichier Markdown dans le dossier docs/.

Voilà, votre fichier Markdown est rendu, mais il reste une étape.

On peut aussi créer les fichiers HTML avec cette commande :

mkdocs build

Test des fichiers HTML ouverts directement dans Firefox

Installation d'un template

Je vais installer le template "material" avec cette commande

pip3 install mkdocs-material

J'ai testé d'autre template comme Cinder Theme for MkDocs qui sont aussi très jolis.

Activation du template

La partie de personnalisation du site se fait via le fichier mkdocs.yml qu'on va éditer

vim mkdocs.yml

Je vais renommer le site et activer le template et configurer mes menus avec ce code :

site_name: Be Cloud, code it !
theme: 
  name: material
  logo: logo_b_cloud_code_it_transp.png
  favicon: favicon.ico

nav:
  - Accueil: index.md
  - Articles: article/articles.md
  - Procédure: procedure/procedure.md
  - A Propos: a-propos.md

J'en profite pour ajouter un logo et un favicon.

Ainsi que la structure pour les autres pages du site.

Ajouter les commentaires

Comment ajouter les commentaires mastodon a Mkdocs

Ajouter le zoom dans les images

Installer ce plugin

pip install mkdocs-glightbox

Dans le fichier mkdocs.yml ajouter

plugins:
- glightbox

To Be continue

Je rebuild et je livre cette version du site avec cette commande

mkdocs build

Un coup de FileZilla et c'est livré.

Prochainement la CICD

Je ferai un article sur comment livrer le site automatiquement quand je mettrai la CI/CD en place.

Commentaire

Commentez cet article de blog en utilisant un compte compatible Fediverse (Mastodon ou similaire).