Introduction

Avec le nombre d’informations qui arrivent vers moi chaque jour dans de nombreux domaines, des pages de notes manuscrites éparpillées un peu partout et jamais réutilisées, et toujours le souci de régler un problème pour la énième fois sans se souvenir de la solution comme les toutes les fois précédentes. 😆

Il me manquait donc un outil pour me servir de second cerveau 🧠 afin d’avoir toutes ces pages de notes ou ces erreurs déjà résolues rassemblées au même endroit.

L’expression du besoin était de ce fait présente, avec des conditions obligatoires qui se sont dessinées au fil des différents tests :

• Rapidité d’accessibilité
• Rédaction des pages en Markdown
• Outil léger
• Hébergement local

Qu’est ce que MkDocs ?

MkDocs est un générateur de site statique rapide et simple, destiné à la création de documentation. Les fichiers de la documentation sont écrits en Markdown et configurés à l’aide d’un seul fichier de configuration YAML.

Cette définition présente sur le site de MkDocs m’a directement inspiré une fois que je suis tombé dessus, car ceci répondait à mes 4 besoins exprimés ci-dessus, et j’ai donc décidé de me lancer dans le test de cet outil.

La première version de mon wiki utilisait cet outil. J’ai utilisé un Dockerfile afin de pouvoir conteneuriser l’outil et de pouvoir l’utiliser en local sans besoin d’installer le paquet python mkdocs.

Seul bémol de cet outil est que l’interface utilisateur pique un peu les yeux. C’est ceci qui m’a motivé à trouver un thème !

Material

Material est un framework qui s’utilise par-dessus MkDocs et va ainsi permettre de générer un site statique personnalisable via une multitude d’options, mais également la possibilité d’ajouter des plugins.

Ceci va permettre d’avoir un rendu très propre tout en minimisant la partie configuration, car bon nombre de fonctionnalités sont déjà intégrées dans le framework et une simple ligne dans le fichier de configuration permet de les ajouter.

Mise en place du wiki

Pour mettre en place cet outil, la documentation de Material explique le déploiement via l’utilitaire mkdocs ou via conteneur docker. Pour ma part, je suis parti sur l’option docker afin de pouvoir utiliser ce conteneur dans mes différents environnements sans besoin d’avoir l’utilitaire présent sur toutes mes machines.

Pour commencer, il faut commencer par initialiser le projet dans le but de créer le squelette de notre wiki. Pour ceci, on passe la commande new . au conteneur docker possédant déjà l’utilitaire mkdocs en entrypoint.

1

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .

Une fois le projet initialisé, on se retrouve avec l’arborescence suivante :

1
2
3
4

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

• docs : Représente l’arborescence de notre wiki
• mkdocs.yaml : Fichier de configuration du wiki

Configuration

Pour la configuration du wiki, celle-ci s’effectue via le fichier mkdocs.yaml à la racine du projet. On va pouvoir y configurer le thème ainsi que les features que l’on souhaite qui sont disponibles ici. Mais également les extensions pythons que l’on souhaite utiliser.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

# Configuration du site
site_name: My site
site_url: https://mydomain.org/mysite

# Configuration du thème material
theme:
  name: material
  icon:
    repo: fontawesome/brands/gitlab
  logo: assets/logo.png
  # Ajout de features
  features:
    - content.code.copy
    - navigation.instant
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.sections
    - navigation.path
    - navigation.top
  # Automatic light & dark mode
  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
# Déclaration des plugins du thème material
plugins:
  - search

# Extension python pour le markdown
markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - admonition
  - pymdownx.details
  - pymdownx.superfences
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Dans mon cas, j’ai ajouté différentes features permettant par exemple de copier les blocs de code, d’avoir des onglets par nom de sections ou bien le choix entre light & dark mode. J’ai ajouté le plugin search afin d’avoir une barre de recherche dans mon wiki.

J’ai ajouté des extensions pythons permettant de mettre des émojis, des schémas mermaid ou bien d’ajouter des classes HTML/CSS à mes blocs de markdown.

Ajout de contenu

Pour ce qui va être du contenu, il se situera sous le répertoire docs/, chaque dossier représentera une section et chaque fichier représentera une page.

Il est possible de créer une architecture très modulable en ayant N section avec N sous-section et N fichier par sous-section. Ou bien créer uniquement des fichiers. Le fonctionnement laisse un libre recours à l’imagination.

Le nom de dossier représentera le nom de la section / sous-section et pour les pages, le titre sera le nom du fichier ou le header (# Titre1) en markdown s’il y en a 1.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

docs/
├── assets
│   └── logo.png
├── Plantes
│   ├── ficus.jpg
│   └── Ficus.md
└── Tech
    ├── Git
    │   └── config.md
    └── Golang
        └── issues.md

Déploiement

Pour la partie déploiement, je lance ce projet en local dans un conteneur docker via le fichier docker-compose.yml, car je n’ai pas l’intérêt de l’héberger sur le web actuellement.

1
2
3
4
5
6
7
8
9

services:
  mkdocs-material:
    restart: "always"
    ports:
      - "8000:8000"
    container_name: "wiki"
    volumes:
      - "/path/to/wiki:/docs"
    image: "squidfunk/mkdocs-material"

Conclusion

Je pense que l’ajout de ce wiki dans ma boîte à outils va me servir de plus en plus avec le temps. Toutes les connaissances acquises vont être regroupées au même endroit et triées par domaine. Ceci va me permettre une facilité et rapidité d’accès à l’information, augmentant donc ma productivité et amenant par la même occasion une réduction de ma perte de temps.