Morgenbord : Documentation

J’ai toujours aimé qu’une documentation soit propre, facile à éditer et facile à naviguer. J’aime le markdown, c’est propre, lisible, et ça remplit sa mission d’être lisible même sans interpréteur. Je pense que beaucoup plus d’interfaces devraient proposer du markdown et je me réjouis que la plupart des chats et réseaux sociaux modernes sachent l’interpréter.

Pour publier une documentation il y a une diversité extraordinaire de possibilités. Laissons de côté les CMS comme MediaWiki et autres outils purement en logiciel. Je veux que la documentation soit consultable dans sa forme la plus simple possible, des fichiers textes ! Je veux pouvoir la lire directement dans le dépôt GitHub ou dans mon IDE. Je veux aussi que la version en ligne aie une mise en page simple, moderne, avec un thème. Je veux le moins de code possible pour garder l’impression que ma documentation est surtout faite de fichiers textes. Je veux que l’arborescence corresponde à la navigation.

Malgré mes exigences élevées, j’ai énormément de choix. J’ai finalement choisi Vitepress. D’abord parce que Vitepress fait partie de l’écosystème Vue et que c’est tout à fait cohérent de l’adopter alors que Morgenbord utilise aussi Vue.js. Ensuite, je l’apprécie pour sa légèreté. Regardez à quoi ça ressemble à la racine.

.
├── .github 
├── .vitepress
├── .obsidian
├── App
├── Core
├── Widgets
├── node_modules
├── public
├── .gitignore
├── Getting started.md
├── index.md
├── Installation.md
├── Introduction.md
├── README.md
├── package.json
└── yarn.lock 

On y trouve plus de fichiers markdown qu’autre chose et c’est parfait comme ça ! J’en profite pour vous le détailler un peu. Là où je ne précise rien, ce sont des fichiers markdown ou des dossiers qui en contiennent.

.
├── .github − La configuration pour GitHub Actions
├── .vitepress − Trois fichiers de configuration en TypeScript
├── .obsidian − Mon petit logiciel préféré, je vous en reparle
├── App
├── Core
├── Widgets
├── node_modules − Le fameux
├── public − Le dossier pour tous les assets
├── .gitignore − Pour ignorer node_modules et le dossier de build
├── Getting started.md
├── index.md
├── Installation.md
├── Introduction.md
├── README.md
├── package.json − Il faut au moins ça, voyons !
└── yarn.lock − Pour verrouiller les versions de chaque dépendance

J’ai l’impression de pouvoir me concentrer pleinement sur le contenu plutôt que le contenant. Tout est versionné avec git au lieu de trouver une méthode avec une base de données. On peut discuter des sujets en issues au lieu d’une discussion de type wiki. Ça utilise pleinement les habitudes des développeurs. Je suis ravi !

Pour le thème on ne va pas se casser la tête. Il y a un thème basé sur Catppuccin, encore lui, qui va me permettre d’avoir les même couleurs dans la documentation et dans le projet. Peut-être que je pourrais unifier les typographies aussi mais ce n’est pas encore le cas et ce n’est pas urgent.

J’ai décidé de ne pas héberger la documentation moi-même uniquement pour m’obliger à utiliser GitHub Actions et tout déployer sur des pages GitHub. Au cas où vous seriez passé à côté de l’information, je suis un développeur freelance et Morgenbord est un vrai projet que je prends au sérieux. Notez toutefois que ce projet me sert aussi d’excuse pour étaler sous vos yeux toutes mes compétences, mon état d’esprit, ma rigueur et même mes frivolités. Vous savez maintenant que je sais utiliser GitHub Actions et comme c’est une technologie ultra complexe à mettre en place (c’est faux), c’était un plaisir pour moi de l’ajouter à ma liste de compétences (c’est vrai).

Il reste un dossier caché, /.obsidian. Mon logiciel préféré, celui qui est tout le temps démarré, présent sur mon laptop aussi bien que sur mobile, c’est Obsidian. Pour une fois il s’agit d’un logiciel propriétaire, certes, moi qui défend tellement le logiciel libre. Obsidian est si puissant, et si libre ! Je fais plein de choses avec mais ce n’est pas le sujet du jour. Il me propose de nombreuses fonctionnalités qui m’ont toutes emballé.

• Éditer le markdown en WYSIWYG.
• Avoir une interface pratiquement identique au rendu final avec Vitepress, donc le même thème.
• Utiliser un correcteur efficace en anglais, j’ai choisi Harper.
• Consulter la documentation hors ligne avec la même aisance que sur le site.
• Mettre à jour automatiquement les liens vers un fichier s’il est renommé.
• Utiliser la plupart des raccourcis claviers et automatisation que la plupart des IDE.
• Cacher les dossiers superflus comme les dossiers avec un . et /node_modules.

Il faudra bien sûr installer Obsidian sur votre système pour lire la documentation avec mais tout est configuré dedans pour éditer sans avoir à modifier quoique ce soit.

Pour consulter la documentation dans se version web, si vous n’utilisez pas le site mais que vous l’exécuter en local, tout démarre avec yarn dev. Pour le reste il faudra suivre le README.

Attention c’est un début de documentation. J’en suis encore au début du projet et je n’ai pas forcément assez de matière pour tout rédiger. Chaque chose en son temps. Ça n’empêche pas d’admirer le résultat !

Pour voir le code ça se passe sur https://github.com/PointPlusYt/morgenbord-documentation
Pour voir le projet GitHub et suivre son avancée : https://github.com/orgs/PointPlusYt/projects/1?pane=info