Le document 2.0 - Maîtrise des formats ouverts, Markdown et interopérabilité

Cet article présente une méthodologie minimaliste qui met en lumière les avantages des formats ouverts, de la syntaxe Markdown et de l’interopérabilité pour garantir la pérennité et l’accessibilité de tes informations.

🌘 Markdown : Simplicité pour la Documentation

Le Markdown est une syntaxe légère conçue pour écrire des textes et de la documentation de manière lisible et intuitive. Inspirée des notations courantes dans les courriels, elle permet de structurer du contenu sans se préoccuper du formatage final.

🌘 Pourquoi choisir Markdown ?

• Simplicité : La documentation complète de Markdown tient sur une seule page. L’apprentissage et l’adoption sont rapides.
• Lisibilité : Les documents Markdown sont lisibles directement, sans rendu.
• Légèreté : Les fichiers sont petits, facilitant stockage et partage.

🌘 Les “Saveurs” de Markdown

Il n’existe pas de standard unique pour Markdown, mais plusieurs “saveurs” qui ajoutent des fonctionnalités spécifiques. Les différences sont généralement minimes. Voici les plus populaires :

GitHub Flavored Markdown (GFM)
: Utilisé sur GitHub pour la documentation de projets.

R Markdown
: Idéal pour créer des rapports statistiques élégants et reproductibles, intégrant du code R.

Pandoc Markdown
: Une variante riche en fonctionnalités, parfaite pour la conversion automatisée de documents vers de multiples formats.

🌘 Éditeurs Recommandés pour Markdown

Plusieurs éditeurs de code supportent nativement Markdown, offrant des aperçus en temps réel et des aides à la syntaxe :

🌘 L’omniprésence de Markdown

Markdown est utilisé bien au-delà des éditeurs de code. Tu le retrouves sur des forums comme Discord et Discourse, ainsi que sur des plateformes de blog comme Ghost, Jekyll ou 11ty. À titre d’exemple, l’intégralité du site jevalide.ca est rédigée en Markdown et générée en site statique avec 11ty. Sa simplicité et sa polyvalence en font un standard pour la rédaction web et la communication.

🌘 Interopérabilité : Formats Ouverts et Pandoc

L’interopérabilité est la capacité des systèmes à échanger des informations. Les formats ouverts sont des spécifications de fichiers publiquement disponibles, sans restrictions légales ou financières. Ils sont essentiels pour la pérennité de l’information et pour éviter la dépendance aux logiciels propriétaires.

Pandoc est l’outil de choix pour la conversion de documents.

🌘 Pandoc : L’Outil Universel de Conversion Documentaire

Pandoc est un outil en ligne de commande et une bibliothèque (écrite en Haskell) qui convertit des fichiers entre une multitude de formats ouverts. Si ton éditeur exporte vers divers formats, il y a de fortes chances que Pandoc soit le moteur sous-jacent.

Pandoc est multi-plateformes. Certaines fonctionnalités peuvent nécessiter des logiciels tiers (ex: Microsoft Word ou LibreOffice pour les .docx).

🌘 Formats d’Entrée et de Sortie Supportés par Pandoc

Pandoc supporte une vaste gamme de formats, ce qui en fait un indispensable pour l’interopérabilité :

Formats d’entrée :

• Markdown
• DocBook
• LaTeX
• OpenDocument
• Epub
• Etc.

Formats de sortie :

• HTML/CSS/JavaScript (HTML5, Slidy, RevealJS)
• OpenDocument
• EPub
• DocBook
• LaTeX
• PDF
• Markdown
• MediaWiki
• DokuWiki
• Etc.

🌘 Installation de Pandoc

L’installation de Pandoc varie selon ton système d’exploitation. Voici les instructions pour les plateformes courantes :

🌘 Windows

Pour une utilisation portable (clé USB, disque réseau, sans droits administrateur) :

1. Télécharge la dernière version de Pandoc pour Windows depuis la page des releases GitHub de Pandoc.
2. Installe MikTeX Portable si tu as besoin de produire des PDF, depuis cette page.

🌘 MacOS

Via Homebrew (recommandé) :

brew install pandoc

Note : Cette commande utilise Homebrew, un gestionnaire de paquets pour macOS, pour installer Pandoc.

Sinon :

1. Télécharge la dernière version de Pandoc pour macOS depuis la page des releases GitHub de Pandoc.
2. Installe BasicTeX avec BasicTeX.pkg depuis cette page.

🌘 Linux

Pour Debian, Ubuntu, etc. :

sudo apt-get install pandoc texlive-base

Note : Cette commande utilise apt-get (gestionnaire de paquets Debian) pour installer Pandoc et texlive-base (nécessaire pour les PDF via LaTeX).

Pour RedHat, etc. :

sudo yum install pandoc

Note : Cette commande utilise yum (gestionnaire de paquets RedHat) pour installer Pandoc.

(Note : RedHat n’inclut pas TeX Live dans ses dépôts par défaut. Télécharge-le manuellement via les instructions ici).

🌘 Fonctionnalités Avancées de Pandoc Markdown

Pandoc Markdown est une extension du Markdown standard. Il offre des fonctionnalités supplémentaires pour des documents riches.

🌘 Blocs de Lignes

Les blocs de lignes séparent manuellement le texte. Utile pour adresses ou citations.

Exemple de code Markdown :

Hôtel de ville de Lévis et Bureau de la mairie
2175, chemin du Fleuve, 
Lévis, G6W 7W9

Note : Le caractère | au début de chaque ligne indique un bloc de lignes. Les lignes vides sont respectées pour le formatage.

🌘 Tables Simples

Pandoc crée des tables simples avec une syntaxe intuitive, via l’extension +simple_tables.

Exemple de code Markdown :

| Droite  | Gauche | Centre | Defaut |
| -----:  | :----- | :----: | ------ |
| 12 | 12 | 12 | 12 |
| 123 | 123 | 123 | 123 |

Table:  Demonstration de la syntaxe des tables simples.

Note : La première ligne définit les en-têtes. La deuxième ligne (-----:, :-----, :----:, ------) définit l’alignement des colonnes. Les lignes suivantes contiennent les données. La ligne Table: ... ajoute une légende.

🌘 Métadonnées

Les métadonnées (titre, auteur, date) sont définies dans l’en-tête du document avec l’extension +pandoc_title_block.

Exemple de code Markdown :

---
title: 'Le document 2.0 - Maîtrise des formats ouverts, Markdown et interopérabilité'
date: '2025-07-19'
author: 'François Pelletier'
---

Note : Ce bloc YAML (Yet Another Markup Language) est au début du document, délimité par ---. Il contient des informations structurées (titre, auteur, date).

🌘 Mathématiques

Pandoc traite les équations mathématiques en syntaxe LaTeX. Il utilise MathML, MathJaX ou AMS LaTeX. Les contenus mathématiques sont encadrés par $ (en ligne) ou $$ (multilignes).

Exemple de code Markdown :

$$
{\begin{aligned}
&\gamma _{ij}(x,t) \\ 
=&\sum _{k=1}^{N}\sigma _{ik}(x,t)\sigma _{jk}(x,t)
\end{aligned}}
$$

Note : Ce bloc de code LaTeX représente une équation mathématique. Les doubles dollars $$ indiquent une équation affichée en bloc. \begin{aligned} et \end{aligned} sont des environnements LaTeX pour aligner les équations.

🌘 Automatisation et Publication

L’approche “Document 2.0” permet d’automatiser la production de différents formats à partir d’une source Markdown unique.

🌘 Produire des Présentations Facilement

À partir d’un fichier Markdown, tu peux générer des présentations HTML (Slidy, RevealJS) ou des PDF.

Exemple de script Bash pour la conversion :

#!/bin/bash
pandoc -f markdown+simple_tables+pandoc_title_block \
  -t html document2_0.md -o document2_0.html --template template.html \
  --css template.css --mathjax --toc --toc-depth 2

pandoc -f markdown+simple_tables+pandoc_title_block \
  -t slidy document2_0.md -o document2_0_slidy.html \
  --css template.css --mathjax --toc --toc-depth 3

Détails de la commande :

• #!/bin/bash : Indique que le script doit être exécuté avec Bash.
• pandoc : La commande principale de Pandoc.
• -f markdown+simple_tables+pandoc_title_block : Spécifie le format d’entrée (Markdown) avec les extensions pour les tables simples et les métadonnées.
• -t html ou -t slidy : Spécifie le format de sortie (HTML ou Slidy pour les présentations).
• document2_0.md : Le fichier source Markdown.
• -o document2_0.html ou -o document2_0_slidy.html : Le nom du fichier de sortie.
• --template template.html : Utilise un modèle HTML personnalisé.
• --css template.css : Applique une feuille de style CSS.
• --mathjax : Active le rendu des équations mathématiques via MathJax.
• --toc : Génère une table des matières.
• --toc-depth N : Définit la profondeur de la table des matières.

🌘 Publier sur un Wiki ou un Site Web

Pandoc exporte le contenu vers des syntaxes de wiki (ex: DokuWiki), facilitant la publication collaborative.

Exemple de script Bash pour la conversion vers DokuWiki :

#!/bin/bash
pandoc -f markdown+simple_tables+pandoc_title_block \
 -t dokuwiki -s presentation.md -o presentation.dokuwiki

Détails de la commande :

• #!/bin/bash : Indique que le script doit être exécuté avec Bash.
• pandoc : La commande principale de Pandoc.
• -f markdown+simple_tables+pandoc_title_block : Spécifie le format d’entrée (Markdown) avec les extensions.
• -t dokuwiki : Spécifie le format de sortie DokuWiki.
• -s presentation.md : Le fichier source Markdown.
• -o presentation.dokuwiki : Le nom du fichier de sortie au format DokuWiki.

🌘 Conclusion

Adopter les formats ouverts, Markdown et Pandoc est une approche qui garantit la simplicité, la lisibilité, l’interopérabilité et la pérennité de tes documents. C’est une philosophie qui te permet de reprendre le contrôle de tes données et de les rendre accessibles sur le long terme.