Convertisseur en ligne gratuit de ASCIIDOC en MD

GitHub, GitLab et de nombreux outils de documentation acceptent Markdown, mais pas AsciiDoc. Un fichier .adoc peut donc nécessiter une conversion avant d’être publié ou modifié dans ces environnements. La conversion en .md conserve la source lisible tout en adaptant les titres, les listes, les liens et les blocs de code à la syntaxe Markdown.

Qu’est-ce que le format ASCIIDOC ?

AsciiDoc est un format de balisage en texte brut utilisé pour la documentation logicielle, les manuels, les livres, les notes de version et les fichiers README. Les extensions courantes comprennent .adoc, .asciidoc et .ad.

Les fichiers AsciiDoc sont généralement créés ou traités avec Asciidoctor, l’implémentation moderne en Ruby, ou avec l’ancien processeur AsciiDoc. Des éditeurs tels que Visual Studio Code, IntelliJ IDEA et des outils de documentation dédiés peuvent également créer ces fichiers, car la source est du texte ordinaire.

AsciiDoc prend en charge les attributs, les directives include, les blocs d’admonition, les tableaux, les références croisées, les diagrammes, les citations et les structures de documents réutilisables. Certaines de ces fonctionnalités n’ont pas d’équivalent direct en Markdown.

Qu’est-ce que le format MD ?

MD est l’extension habituelle des fichiers Markdown. Markdown est un format de texte brut léger conçu pour offrir une source lisible et un rendu HTML facile. GitHub, GitLab, Bitbucket, les générateurs de sites statiques, les wikis, les applications de prise de notes et les éditeurs de code le prennent couramment en charge.

Markdown est une cible pratique lorsqu’un dépôt exige un fichier README.md, lorsque les collaborateurs modifient la documentation avec des outils orientés Markdown ou lorsque les fichiers source doivent être affichés de manière cohérente sur différentes plateformes d’hébergement de code. GitHub Flavored Markdown (GFM) ajoute les tableaux, les listes de tâches, les liens automatiques et les blocs de code délimités.

Comment convertir réellement ASCIIDOC en MD

Pour effectuer une conversion locale, installez Pandoc, puis exécutez :

pandoc input.adoc -f asciidoc -t gfm -o output.md

Remplacez input.adoc par le nom du fichier source et output.md par le chemin de destination souhaité. L’option -f asciidoc sélectionne le lecteur AsciiDoc, -t gfm génère du GitHub Flavored Markdown et -o écrit le résultat dans un fichier.

Pour convertir un fichier portant l’extension .asciidoc, utilisez son nom réel :

pandoc manual.asciidoc -f asciidoc -t gfm -o manual.md

Si la version installée de Pandoc ne fournit pas de lecteur AsciiDoc, utilisez Asciidoctor pour créer d’abord un fichier DocBook XML, puis convertissez ce fichier intermédiaire :

asciidoctor -b docbook5 -o intermediate.xml input.adoc
pandoc intermediate.xml -f docbook -t gfm -o output.md

Pour une option sans installation, téléversez le fichier source sur 101convert.com, choisissez Markdown comme format de sortie, démarrez la conversion, puis téléchargez le fichier .md obtenu. Évitez de téléverser des documents contenant des informations confidentielles ou à accès restreint.

Limites de qualité et de compatibilité

La conversion n’est pas toujours sans perte. Les attributs AsciiDoc, le contenu conditionnel, les inclusions, les rôles personnalisés, les macros, les extensions, les tableaux complexes, les admonitions et les références croisées peuvent être simplifiés, omis ou générés sous forme de balisage brut.

Vérifiez le Markdown généré afin de contrôler les niveaux de titre, l’imbrication des listes, le formatage des tableaux, les chemins d’image, les délimiteurs de code, les liens et les caractères échappés. GFM prend en charge les tableaux et les listes de tâches, mais d’autres analyseurs Markdown peuvent afficher ces fonctionnalités différemment.

Les inclusions AsciiDoc peuvent nécessiter un prétraitement avant la conversion. Résolvez les fichiers référencés par les directives include:: et vérifiez que les chemins relatifs des images et des liens pointent toujours vers les emplacements appropriés après le déplacement du fichier de sortie.