Plutôt que d'utiliser un éditeur HTML comme BlueGriffon, je vous recommande d'emblée et au préalable la rédaction de votre documentation au format markdown, cela vous rendra certainement plus productif car vous pourrez vous concentrer uniquement sur le contenu tout en ayant l'assurance que votre documentation respectera strictement la mise en page et la charte graphique que vous aurez choisie. Sans parler d'automatisation puisque vous pourriez même le produire directement et simplement depuis une base de données ou une application disposant d'une Interface de programmation — Wikipédia ou de fichiers dans un format ouvert.
Néanmoins, vous en conviendrez, comme markdown n'est pas nécessairement ce qu'il y a de plus lisible ou accessible, il est préférable de l'exporter ensuite dans un autre format comme le HTML5. Soit sous forme de présentation dynamique (avec par exemple les frameworks reveal.js, S5, HTML Slidy, etc.) soit dans un(des) fichier(s) statique(s).
Dans le cas du HTML5 statique plusieurs options sont possibles : soit utiliser des solutions dédiées aux développeurs comme DAUX.IO ou MkDocs qui sauront parfaitement l'analyser, soit comme je vais vous le présenter (selon le principe KISS), en utilisant seulement Pandoc et un thème.
N.B : si vous n'avez pas le temps de convertir la documentation ou que vous souhaiteriez qu'elle soit directement publiée sur un serveur web dont vous n'aurez pas accès au backend utilisez un un wiki comme Wiki.js
Dans cet exemple mon choix se porte sur le thème de GitHub compte tenu du fait qu'il est complet, qu'il a déjà fait ses preuves et qu'il semble respecter des principes d'accessibilité (à confirmer).
Enfin, afin de rendre le document aussi portable qu'un fichier généré par traitement de texte (Word, LibreOffice) ou un PDF il sera préférable de ne générer qu'un fichier plutôt qu'un dossier contenant un fichier HTML et ses ressources numériques (images par exemple)
Prérequis
Pandoc
Installation
Pour les Debian, Ubuntu et autres dérivées :
sudo apt install pandoc
Pour les Redhat, Fedora et autres dérivées :
sudo dnf install pandoc
Pandoc Github flavored HTML5
Installation
git clone https://github.com/tajmone/pandoc-goodies.git
mkdir -p ~/.pandoc/templates/
cp -r pandoc-goodies ~/.pandoc/templates/
Conversion
Après rédaction de votre fichier au format Markdown utilisez la commande suivante :
pandoc --template=GitHub.html5 --self-contained test.md -o documentation.html
dans laquelle :
- test.md est le nom du fichier source Markdown
- documentation.html le nom de la documentation produite
- --self-contained est l'option qui vous permet de tout fusionner dans un seul fichier HTML
Démonstration
GitHub Pandoc HTML5 Template — Preview
Cet article de blog
