Découverte de Mkdocs

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

J'ai voulu POC 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 procedure a été réaliser sur un os linux ( PopOs 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 etre 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 en automatique.

mkdocs new blog
cd blog/
mkdocs serve

Je depose un fichier markdown dans le dossier docs/

Voila 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 en HTML ouvert directement dans Firefox

Installation d'un template

Je vais installer le template "material" avec cette commande

pip3 install mkdocs-material

J'ai tester d'autre template comme Cinder Theme for MkDocs qui sont aussi très jolie.

Activation du template

La Partie de customisation du site ce fait via le fichier mkdocs.yml qu'on va éditer

vim mkdocs.yml

Je vais renommer le site et activer le template et faire mes menu 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 en automatique quand je mettrai la CICD en place.

Commentaire

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