Migrer du Markdown à la rédaction structurée
Publié le 24 janvier 2023 par Andrew Owen (4 minutes)
Je suis un grand fan de Markdown. Il est parfait pour les wikis et la rédaction de contenu pour les sites statiques (la plupart du contenu de ce site est rédigé à l’aide de ce langage). Mais il arrive un moment dans la documentation d’un logiciel où la taille du projet ou le nombre de contributeurs a augmenté au point qu’il est nécessaire d’imposer une certaine structure. C’est à cela que servent les documents structurés. L’une des principales raisons pour lesquelles vous souhaitez le faire est de séparer le contenu de la présentation. Cela vous permet de présenter le contenu de différentes manières sur différents supports, tels que l’imprimé et l’Internet. Mais vous avez déjà tout ce contenu en Markdown. Quelles sont donc les options qui s’offrent à vous: Vous pouvez tout recréer à partir de zéro (ne le faites pas). Ou vous pouvez migrer de Markdown vers un système de rédaction structuré.
J’ai beaucoup écrit sur mon enthousiasme pour DocBook. À mon avis, c’est la meilleure façon de faire de la rédaction structurée. Mais peut-être en êtes-vous au stade où la plupart de vos documents sont rédigés par des développeurs et où vous n’avez pas de rédacteur technique dans l’équipe. Soit dit en passant, pourquoi les documents sont-ils toujours la priorité la plus basse dans le développement de logiciels, alors qu’ils peuvent être le facteur décisif pour un client qui envisage d’acheter votre logiciel: Il existe un juste milieu entre Markdown et DocBook, qui s’appelle AsciiDoc. Vous écrivez toujours en texte brut et le format de balisage est suffisamment proche de Markdown pour que les développeurs puissent rapidement s’y familiariser. Mais sous le capot, la structure est la même que DocBook et vous pouvez exporter dans ce format.
La méthode standard pour convertir une documentation d’un format à un autre est Pandoc. Cependant, lorsqu’il s’agit de Markdown, il existe une meilleure méthode, décrite par Matthew Setter dans son blog. Créé par Dan Allen d’Asciidoctor, Kramdoc est une extension Markdown vers Asciidoc pour kramdown (un outil de conversion Markdown créé par Thomas Leitner). Le principal prérequis est Ruby, qui est généralement déjà installé sur Linux et les versions récentes de macOS. Il y a plusieurs façons d’installer Ruby sur Windows, mais je recommande généralement d’utiliser le gestionnaire de paquets Scoop. Une fois Ruby installé:
gem install kramdown-asciidoc
Vous aurez également besoin d’Asciidoctor lui-même. Sous Linux, vous devriez pouvoir utiliser votre gestionnaire de paquets préféré. Sur macOS, je recommande d’utiliser Homebrew (brew install asciidoctor). Sous Windows, vous pouvez utiliser gem install asciidoctor. Ensuite, pour convertir un fichier Markdown individuel en Asciidoc, entrez: kramdoc -o=output.adoc input.md. Voir l’article de Mattew Setter mentionné précédemment pour une approche de la conversion par lots. Lorsque vous avez obtenu tout votre contenu au format Asciidoc, vous devez construire la structure du document. Il s’agit en fait d’une table des matières. Vous pouvez ensuite publier au format HTML. Mais il existe également un plug-in si vous souhaitez publier au format PDF.
L’une des différences entre Asciidoc et le Markdown standard est qu’il prend en charge la rédaction structurée. Dans le cas d’une rédaction non structurée:
Mais avec la rédaction structurée:
Et si au fil du temps vous trouvez que même Asciidoc n’est pas assez avancé pour vous, alors vous pouvez passer au DocBook (asciidoctor -b docbook contents.adoc).
L’article de cette semaine est légèrement tronqué parce que j’ai réussi à cliquer accidentellement sur le bouton retour de ma souris sans sauvegarder le projet original. J’ai demandé à l’équipe de TinaCMS un avertissement de navigateur “quitter cette page?