Aller au contenu

Mkdocs crée de la documentation en un éclair !

Ah, les joies de créer de la documentation dans le bon vieux format Word. Stockée sur un partage réseau, oh là là, la mise en page, les alignements, que de joies à utiliser Word... En tant que bon informaticien (un peu paresseux), comment puis-je créer ma documentation à partir d'une seule source, d'abord en PDF, puis éventuellement en un site statique ? Et en ce qui concerne le design ? Markdown est la solution ! Et nous sommes sur un blog où PIPELINE et CICD sont au cœur de notre métier.

Présentation

MkDocs est un générateur de sites statiques simple, rapide et orienté vers la création de documentation de projet. La documentation est écrite en Markdown et configurée avec un seul fichier de configuration YAML.

Mise en place d'un projet

Prérequis

  • Python 3
  • Votre éditeur de code préféré (même Vim, vous avez le droit)

Ici, nous travaillons proprement, alors créons notre venv Python : 

python3 -m venv venv

Activons notre venv : 

source venv/bin/activate

Installation

pip install mkdocs

Parfait !

Initialisation d'un projet et découverte de la structure

Pour initialiser un "Projet" : 

mkdocs new cerises

Sortie : 

INFO    -  Creating project directory: cerises
INFO    -  Writing config file: cerises/mkdocs.yml
INFO    -  Writing initial docs: cerises/docs/index.md

Structure : 

cerises/
├── docs
│   └── index.md
└── mkdocs.yml

2 directories, 2 files

Il y a un seul fichier de configuration nommé mkdocs.yml, et un dossier nommé docs qui contiendra les fichiers sources de votre documentation. Pour l'instant, le dossier docs ne contient qu'une seule page de documentation, nommée index.md.

Avec la commande suivante, vous pouvez lancer un serveur web local : 

mkdocs serve

Dans votre navigateur : http://localhost:8000

site par défaut

Mon premier projet

Voici le mkdocs.yml de mon blog personnel : 

site_name: Blog personnel de Kaze
site_author: Kaze
site_url: https://timai-blog.fr

theme:
    name: material
    logo: https://e7.pngegg.com/pngimages/370/339/png-clipart-donald-duck-youtube-comics-cartoon-donald-duck-comics-hat.png
    language: fr

plugins:
    - search
    - blog

  • site_name : C'est le nom du site web.
  • site_author : Il s'agit du nom de l'auteur du site.
  • site_url : C'est l'URL de base du site web. C'est l'adresse à laquelle le site sera accessible en ligne.
  • theme : Cette section configure le thème visuel du site web.
  • name : Spécifie le nom du thème à utiliser. Dans ce cas, le thème est "material". "Material" est un thème populaire basé sur le design Material Design de Google.
  • logo : Vous avez défini un logo personnalisé pour le site en spécifiant son URL.
  • language : Cela indique la langue du site.
  • plugins : Cette section spécifie les plugins à utiliser pour le site.
  • search : Le plugin "search" permet d'ajouter une fonction de recherche au site web.
  • blog : Le plugin "blog" indique que ce site est destiné à être un blog.

Création de ma première page

Créons une fausse page d'exemple : 

curl 'https://jaspervdj.be/lorem-markdownum/markdown.txt' > docs/about.md

Puis lançons le serveur web de développement : 

mkdocs serve

Oh mince, je ne vois pas ma page !

Il faut ajouter dans notre mkdocs.yml la navigation avec la nouvelle page : 

nav:
  - Home: index.md
  - About: about.md

Pow, pow, pow ! Lorem

Thèmes

Vous pouvez créer votre propre thème en utilisant Python et Jinja2, ou utiliser les thèmes de la communauté !

Lien : https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes

Installons le thème "Dracula" : https://github.com/dracula/mkdocs 

pip install mkdocs-dracula-theme

Dans le mkdocs.yml : 

theme:
    name: dracula

Dracula

Exporter en site statique

Rien de plus simple pour convertir en site statique : 

mkdocs build

Vous obtiendrez un dossier site/ à télécharger avec votre meilleur client FTP chez votre hébergeur web.

Mon modèle de site

Voici mon arborescence : 

./
├── docs
│   ├── assets
│   │   └── img
│   │       ├── donald.png
│   │       └── pp.jpg
│   ├── blog
│   │   ├── .authors.yml
│   │   ├── index.md
│   │   └── posts
│   │       ├── 00_cloud-init
│   │       │   ├── cloud-init.md
│   │       │   └── img
│   │       │       ├── add_disque.png
│   │       │       ├── bootorder.png
│   │       │       ├── cloudinitdrive.png
│   │       │       ├── cloudinit.png
│   │       │       └── image.png
│   │       └── 01_convert_raw_to_qcow2
│   │           └── convert_raw_to_qcow2.md
└── mkdocs.yml

mkdocs.yml 

site_name: Blog personnel de Kaze
site_author: Kaze
site_url: https://timai-blog.fr

theme:
    name: material
    logo: https://e7.pngegg.com/pngimages/370/339/png-clipart-donald-duck-youtube-comics-cartoon-donald-duck-comics-hat.png
    language: fr

plugins:
    - search
    - blog

Alors, les explications : j'utilise le plugin blog avec le thème material. J'écris des articles/postes dans le dossier blog/posts. Chaque post a son dossier avec un dossier image. À l'intérieur de blog/posts, j'ai le fichier authors.yml qui me permet de créer ma petite bulle auteur.

authors:
  kaze:
    name: Timaï SELMI
    description: Auteur
    avatar: https://e7.pngegg.com/pngimages/370/339/png-clipart-donald-duck-youtube-comics-cartoon-donald-duck-comics-hat.png

Mon modèle de posts

Mes posts commencent toujours par ces en-têtes : 

---
draft: false
date: 2024-01-27
categories:
  - proxmox
  - devops
  - cloud
  - template
authors:
  - kaze
---

Ensuite, j'ajoute le titre de l'article et un court résumé pour le "teasing" : 

# Proxmox template cloud init

Cloud-Init est un outil permettant d'automatiser la configuration initiale des machines virtuelles. Comme la configuration du nom d'hôte, des interfaces réseau et des clés autorisées. Il peut être utilisé lors du provisionnement de machines virtuelles qui ont été déployées sur la base d'un modèle afin d'éviter les conflits sur le réseau.

<!-- more -->

Le permet de créer un pseudo "slug".

Ensuite, j'écris mon texte.

## 1
Super tuto
## Toto
Super toto

Exemple de .gitlab-ci.yml

image: python:3.12

# Définit les étapes de pipeline
stages:
  - build
  - deploy

variables:
  MKDOCS_BUILD_DIR: "site"

# Étape de construction
build:
  stage: build
  script:
    - pip install mkdocs
    - pip install -r requirements.txt
    - mkdocs build --clean

  artifacts:
    paths:
      - $MKDOCS_BUILD_DIR

# Étape de déploiement
deploy:
  stage: deploy
  script:

Pour la partie deploy, faire via SSH avec rsync ou alors avec un client FTP CLI. Sinon générer un artefact au format zip.