Depuis quelque temps, je reçois régulièrement des e-mails des lecteurs fidèles de ce blog qui veulent savoir pourquoi je ne publie pas de nouveaux articles. Voici donc un petit article pour donner de mes nouvelles à tous les visiteurs de ce site.

Vers le début du printemps, j’ai dispensé une formation Linux + Docker à une équipe d’administrateurs de FranceTV à Paris. J’avais donc le nez dans le guidon pour rédiger des supports de cours adaptés à cette formation. Pendant cette phase de rédaction, j’ai eu l’occasion de réfléchir au format de ma documentation technique. En effet, ces vingt dernières années, j’ai essayé toute une série de formats pour mes articles.

Et puis je suis tombé sur MkDocs, un générateur de sites statiques pour créer des plateformes de documentation. MkDocs est écrit en Python et transforme une série de fichiers écrits en Markdown en un site statique ergonomique et facile à organiser, même s’il contient des centaines voire même des milliers de pages de documentation. J’ai donc testé cet outil, ce qui veut dire que j’ai joué avec pendant quelques jours, jusqu’à ce que j’obtienne une présentation qui me convienne à peu près.

Pour m’entraîner avec MkDocs, j’ai décidé sur un coup de tête d’adopter l’outil pour la rédaction de mes supports de cours pour FranceTV. Le grand avantage, c’est que dorénavant, je ne suis plus obligé à me farcir l’éditeur WordPress. Au lieu de cela, je peux lancer mon éditeur de texte préféré (ah Vim bah ouais ah Vim bah ouais) et stocker mes sources en Markdown sur GitLab.

Évidemment, chaque solution a également ses désavantages qui lui sont propres. À titre d’exemple, je regrette un peu que Markdown n’offre pas la possibilité de mettre des bouts de code en exergue, du moins sans sauter à travers des cerceaux en feu. Mais bon, c’est bien une des rares limitations de l’outil.

En contrepartie, je gagne énormément en flexibilité et en pérennité. Une modification dans un article technique, c’est un coup de Vim et une paire de commandes pour actualiser le site. Et je n’ai pas à me soucier si mes docs restent lisibles dans dix ou vingt ans, vu que le texte simple et le Markdown m’ont l’air d’être faits pour durer. À condition qu’on n’ait pas tous succombé sous la chaleur d’ici-là, je dis ça parce que j’habite le coin de la France qui bat régulièrement les records de température.

Du coup j’en ai profité pour adopter l’outil MkDocs pour ma documentation interne également. Ce sont les HOWTOs de Microlinux, si vous voulez. Le destinataire de cette documentation, c’est tout d’abord moi-même, mais je pense qu’un administrateur système raisonnablement cultivé y trouvera des réponses à ses questions.

Retenez donc ces deux adresses, classez-les dans vos marque-pages et partagez-les allègrement.

Quant à ce blog, je continuerai à m’en servir de façon sporadique pour des annonces comme celle-ci. Un gentil bonjour de la garrigue gardoise.

— Nico


13 commentaires

Simon · 26 juillet 2022 à 23 h 59 min

Bonjour,

Étant abonné au flux RSS du courrier du hacker, j’avais remarqué votre travail de migration vers Mkdocs.
Comme vous, je commence à rédiger grâce à « Material for Mkdocs » la documentation du SI de mon employeur pour ceux qui prendront la suite. Du coup, je suis surpris que vous évoquiez une faiblesse dans la mise en exergue du code.
Cette variante permet justement d’afficher un certain nombre de langages avec la coloration syntaxique adaptée (https://squidfunk.github.io/mkdocs-material/reference/code-blocks/). Ou alors j’ai mal compris ?

    kikinovak · 27 juillet 2022 à 0 h 05 min

    Justement, je ne veux pas de coloration syntaxique. Juste la possibilité de représenter du code en chasse fixe, avec les commandes en gras. Quelque chose dans le genre. On peut le faire, mais c’est sale et compliqué.

      Simon · 27 juillet 2022 à 0 h 45 min

      Soit. Je comprends mieux.

      En tout cas, je suis curieux de lire le contenu de votre formation Docker. J’y suis un peu hermétique et jusqu’à présent j’ai fais en sorte de l’éviter autant que possible, à part pour les trucs très simple (Onlyoffice, Plausible). Votre approche pourrait m’aider à passer le cap.

      C’est l’occasion de vous remercier pour l’ensemble de votre œuvre.

        Simon · 27 juillet 2022 à 2 h 20 min

        *fait. (pardon pour cette grossière erreur.)

Nicolas · 27 juillet 2022 à 10 h 03 min

Bonjour,

Tiens, j’ai l’impression que l’on est de plus en plus qui passent de WordPress à Markdown pour de la documentation technique.
J’ai aussi fait ce cheminement et effectivement, écrire en markdown est plus simple et rapide et avec Wiki.JS j’ai la coloration syntaxique (et une synchro vers github pour « l’archivage » des documentations en dehors de mon propre site).

    Mickael · 30 juillet 2022 à 0 h 00 min

    Bonsoir ! Effectivement, je suis également passé sur du Markdown pour mon blog, l’avantage de la portabilité plus la sauvegarde/archivage sur Gitlab, très pratique. J’hésite également à rajouter une partie Wiki afin de pouvoir stocker quelque part tout ce qui ne « mérite » pas d’être un article on va dire. J’avais de plus en plus de mal avec WordPress de mon côté, beaucoup trop « usine à gaz » pour ma simple utilisation, alors que markdown + Hugo, c’est top.

    Bonne soirée!

      kikinovak · 30 juillet 2022 à 7 h 46 min

      Je ne connais pas Hugo, mais ça fait partie des outils qui sont sur ma liste de choses à apprendre.

cavo789 · 27 juillet 2022 à 14 h 58 min

Bonjour

> je regrette un peu que Markdown n’offre pas la possibilité de mettre des bouts de code en exergue

Je ne comprends pas cette phrase car, sans aucun doute, vous avez dû apercevoir qu’il existe pourtant une notation pour cela; exemple ci-dessous :

« `php
echo « Ceci est un test écrit en PHP et avec un rendu comme tel »;
« `

« `html
Ceci est un test écrit en HTML et avec un rendu comme tel
« `

    cavo789 · 27 juillet 2022 à 15 h 00 min

    Oups… Souci d’interprétation dans le rendu.
    Voir https://enterprise.github.com/downloads/en/markdown-cheatsheet.pdf et la partie « FENCED CODE BLOCKS »

    kikinovak · 28 juillet 2022 à 8 h 13 min

    Certes, mais c’est de la coloration syntaxique automatique, avec un rendu correct dans 99% des cas – et complètement foireux dans 1% des cas. Ce que je cherche, c’est la possibilité de mettre en exergue certaines parties du code. Par exemple, lorsque j’ai un résultat, je veux attirer l’attention du lecteur sur un nom d’une interface réseau, ou une adresse MAC, etc.

lann · 27 juillet 2022 à 19 h 46 min

À titre d’exemple, je regrette un peu que Markdown n’offre pas la possibilité de mettre des bouts de code en exergue,

Emacs et org-mode fait ça avec les blocks :
https://orgmode.org/quickstart.html

Ou alors pour Vim : vim-orgmode
Voir le lien de org mode en fin de page : https://orgmode.org/index.html

Matthieu · 27 juillet 2022 à 19 h 51 min

Bonjour,
Mon service utilise encore des documents Word. ? Je trouve cela tellement peu pratique. Les vieilles habitudes sont difficiles à faire changer.
Comment gérez vous la partie intégration d’images avec mkdocs ? C’est un pré-requis indispensable pour moi. Une image est parfois plus claire qu’un texte.

    kikinovak · 28 juillet 2022 à 8 h 10 min

    Markdown permet d’insérer des images. C’est juste que moi je n’utilise pas cette fonctionnalité.

Les commentaires sont fermés.