Publié le 27 février 2025 par Andrew Owen (5 minutes)
En janvier de l’année dernière, j’étais candidat à un poste de responsable de la documentation et je devais trouver une solution pour répondre aux besoins des rédacteurs et des développeurs-contributeurs. Ma solution ressemblait à peu près à ceci:
J’étais le deuxième choix, donc heureusement pour moi, je n’ai pas eu à le livrer. Au lieu de cela, j’ai obtenu un contrat dans lequel je devais créer un portail de documentation qui présentait les API REST et GraphQL d’une manière assez cohérente. Cette solution était basée sur Magidoc, l’outil gratuit Redocly CLI et beaucoup de scripts. Depuis, j’ai découvert Archbee. Il s’agit d’un système basé sur Markdown avec des extensions propriétaires pour présenter les API REST et GraphQL. Même si j’en avais eu connaissance à l’époque, je ne pense pas que je l’aurais choisi en raison des problèmes de fiabilité documentés. Cependant, après l’avoir utilisé récemment pour un autre client, je pense qu’il pourrait être prêt pour la production de documents destinés aux utilisateurs. Il offre une interface web agréable, mais vous pouvez utiliser votre propre dépôt GitHub comme source de vérité. Les changements effectués dans l’éditeur web créent des demandes d’extraction dans le dépôt. Il dispose d’une fonction de recherche et les sites peuvent être protégés par un mot de passe. Il prend en charge les diagrammes Mermaid et le mode sombre. Son prix est raisonnable et, comme il s’agit de Markdown, vous n’êtes pas bloqué.
Mais je reste un fan de DocBook. Existe-t-il une solution prête à l’emploi qui ressemblerait davantage à ma proposition de système de gestion documentaire (SGD) hybride? Une solution possible serait Magnolia CMS, le générateur de site statique Antora et AsciiDoc. Cependant, Magnolia ne communique pas ses tarifs. Et si vous souhaitez migrer vers un autre système, vous devrez le construire vous-même, car les autres solutions CMS sans tête ne prennent pas en charge AsciiDoc.
Ce qui me ramène à Markdown. Existait-il un SSG dont l’objectif principal était de produire des sites de documentation fonctionnant avec mon headless CMS préféré (TinaCMS)? Cela m’a conduit à Docusaurus. C’est ce que Meta (Facebook) a construit pour remplacer Jekyll comme SSG interne et il utilise React. Ses délais de construction peuvent sembler interminables comparés à ceux d’Hugo. Mais les sites qu’il construit sont tellement plus rapides. Mais existait-il une meilleure intégration des documents de l’API REST libre que de pirater la sortie du CLI de Redocly? La réponse était oui, avec un excellent plugin Docusaurus de Palo Alto Networks. Tout ce que j’aurais dû faire pour le mettre en place était de créer un nouveau site en utilisant le starter Tina Docusarus, puis d’ajouter le plugin. Ce n’était pas si simple. Palo Alto Networks a bu le TypeScript KoolAid. Parce que Docusaurus est React, le site de démarrage créé par Tina utilise JSX. Ils n’ont pas voulu jouer franc jeu. J’ai fini par créer un site à partir du modèle de Palo Alto Networks, puis j’y ai greffé le support de Tina.
Je n’ai pas réussi à trouver un moyen d’activer les widgets de version et de localisation dans la barre de navigation avec la solution Tina, j’ai donc décidé d’utiliser une définition fixe pour ces widgets. Pour la plupart des autres paramètres, Tina utilise des fichiers JSON qui sont référencés par la configuration. L’ajout du support de la recherche Mermaid et Lunr était trivial, bien que la recherche ne fonctionne qu’en production. Plutôt que d’essayer de vous expliquer tout ce que j’ai dû faire pour que cela fonctionne, j’ai pensé cette fois-ci partager simplement le repo. Le composant de Palo Alto Networks est disponible sous la licence MIT, j’ai donc utilisé la même licence. La seule configuration que vous aurez à faire est d’ajouter vos identifiants Tina pour permettre l’édition web en ligne.
Pour en revenir aux exigences, nous avons un repo GitHub avec Actions. Docusaurus remplace Hugo en tant que SSG. Nous utilisons Markdown Extended (MDX) à la place d’AsciiDoc. Nous pouvons toujours utiliser LanguageTool avec TinaCMS et VScode. Nous utilisons Tina à la place de l’éditeur XML Mind. Nous avons des diagrammes Mermaid, avec prévisualisation dans Tina. Nous utilisons Lunr pour la recherche, mais si cela ne suffit pas, il y a un support intégré Algolia. Il existe un plug-in pour Matomo analytics. Il existe un plug-in pour [GraphQL docs] (https://github.com/Zhouzi/docusaurus-graphql-plugin). Docusaurus inclut le support des versions et de la localisation. Nous pouvons toujours utiliser DeepL pour la traduction automatique. Nous pouvons toujours utiliser Pandoc pour l’impression au format PDF ou Word pour l’exportation vers Affinity Publisher.
Ce qui manque, ce sont les variables et le texte conditionnel. J’ai entendu dire que LaunchDarkly était utilisé pour ces derniers. Pour les variables, Syed Muhammad Ali Raza propose une solution sur Stack Overflow:
variables.mdx, avec des composants de variables définis à l’aide de React props.variables.mdx et en le plaçant dans votre page.Lorsque les variables fonctionneront, je mettrai à jour le repo. J’ai déjà fait un peu de codage React pour une solution de commerce électronique, mais c’était il y a longtemps, donc il se peut que vous deviez vous débrouiller tout seul.