Génération de documentation en Markdown

Pour rendre la génération de documentation la plus facile et efficace pour toutes et tous, nous fournissons ici des outils et procédures adaptés à différents profils.

Actuellement, on trouve :

• Des supports de cours
• Des TPs
• Des manuels d'opération de machines
• Des modes opératoires
• Des projets tutorés
• Des rapports de stage,...

Sous des formats aussi divers que :

• Document Word avec une organisation en Sections
• Document Word avec une organisation en tableau "Mode opératoire"
• Document PDF
• Document LibreOffice
• Page de Wiki en syntaxe DokuWiki

Pourquoi Markdown ?

Certains d'entre vous ont peut-être déjà contribué à Wikipedia, au Wiki de l'innovation à l'IUT, ou au wiki d'une autre communauté ouverte. La syntaxe Wiki est inspirée de la syntaxe du code HTML, mais simplifiée pour la rendre lisible et éditable par des contributeurs qui ne sont pas webmaster. Cela permet d'éditer un wiki directement dans le navigateur sans avoir besoin d'un moteur d'édition lourd "WYSIWYG". On clique sur les boutons de l'interface d'édition du wiki pour mettre en forme notre texte. Mais la syntaxe est en fait trop compliquée pour être éditée à la main.

Markdown est le standard de la documentation Open Source. Il est utilisé sur GitHub, GitHub Pages, GitLab pour documenter les projets de logiciel. Il est également supporté par la plupart des Wiki par l'intermédiaire d'Extensions, ainsi que par de nombreux moteurs de sites Web (CMS) tel que Grav. Sa syntaxe est bien plus simple à retenir et rapide à écrire, ce qui permet d'écrire sans cliquer sur des boutons de mise en forme pour plus d'efficacité. De plus, son aspect standard permet de transférer facilement d'un site web vers un wiki ou une forge logicielle, et de l'éditer directement sur son ordinateur pour pouvoir l'imprimer pour générer une documentation papier.

Les différents standards markdown

Il existe une syntaxe standard Markdown, dont les fonctionnalités de mise-en-forme sont limitées, et des dérivés qui supportent le standard et y ajoutent des fonctionnalités non-standard, qui ne seront donc pas correctement mises en forme sur tout site web :

• Markdown
  • Traditional Markdown
  • Markdown Extra
• syntaxe Extended

  • dsg

    • GitHub-Flavored Markdown
• Syntaxe Markdown DokuWiki via le plugin mdpage

Le Markdown dans Bookstack

Bookstack possède sa propre syntaxe markdown qui permet de faire par exemple plus de choses avec les tableaux.

YesWiki Markdown

YesWiki était un autre wiki envisagé pour le wiki de l'IUT, on a finalement opté pour Bookstack.

• Ne supporte a priori que la syntaxe Extended https://yeswiki.net/?DocMarkdown

Wiki.js

Wiki.js était un autre wiki envisagé pour le wiki de l'IUT, on a finalement opté pour Bookstack.

• https://docs.requarks.io/guide/intro

Astuces de syntaxe markdown

• Créer un retour à la ligne dans une cellule de tableau
  • Hack avec syntaxe extended = extra?
  • Bug <br />

Conversion format Word (.docx) vers Markdown (.md)

Si le document Word reste suffisamment simple, il est possible de convertir automatiquement le contenu en Markdown avec une mise en forme correcte sans post-traitement.

Prérequis

Organisation en Sections

Si la syntaxe du document Word reste simple :

• Des Titres et des paragraphes de texte
• De la mise en forme gras, italique, code machine
• Puces et puces numérotées
• Seulement des images, pas de formes ou graphiques Office
• Pas de sommaire

Organisation en Tableau

Les tableaux sont supportés de manière limitée par la syntaxe Markdown de base.

1. Veiller à ce que une case d'un tableau ne contienne pas de puces
2. Sauvegarder et Supprimer les images qui devront être réimportées dans le site de destination

Installation des outils

Installation de l'outil de conversion universel Pandoc

Linux

• sur Ubuntu
• sudo apt install pandoc

Windows

• Page de la dernière version de pandoc
• Télécharger le fichier .msi, par exemple pandoc-3.1.13-windows-x86_64.msi

Procédure

• Ouvrir un Terminal de ligne de commande et se placer dans le dossier du fichier .docx à convertir
• Conversion vers GitHub-Flavored Markdown
• pandoc -f docx -t gfm APAS_mode_operatoire.docx -o apas_mode_operatoire.md
• Copier le contenu dans l'éditeur Mardown de Bookstack
• Eventuellement copier les images une-à-une manuellement

Markdown -> Wiki

La plupart des sites de Wiki supportent une ou plusieurs syntaxe Markdown via des Extensions. Pas besoin donc de traduire le code source d'une syntaxe vers l'autre.

• Syntaxe Markdown DokuWiki via le plugin mdpage
  • Pour écrire du markdown dans une page, il faut :
    • déclarer toute la page comme markdown<!doctype markdown>
    • OU envelopper une partie du texte dans les balises suivantes <markdown> </markdown>
  • https://github.com/mizunashi-mana/dokuwiki-plugin-mdpage/issues/77

DokuWiki -> Markdown

Il existe un plugin dokuwiki pour exporter en markdown :

• https://www.dokuwiki.org/plugin:dw2markdown

Impression de documentation

Markdown -> PDF -> Impression

Installation de Visual Studio Code avec l'extension Office Viewer(Markdown Editor)

• Dans Windows ouvrir l'application Microsoft Store
• Installer Visual Studio Code
• Ouvrir Visual Studio Code
• Dans le menu latéral gauche cliquer sur le dernier bouton Extensions
• Rechercher et installer l'extension Office Viewer(Markdown Editor)
• Ouvrir son fichier Markdown
• Exporter au format PDF

• Noter que cette extension inclut https://github.com/zaaack/vscode-markdown-editor et est basée sur https://github.com/Vanessa219/vditor

BookStack -> PDF -> Impression

• Export d'une page au format PDF