Convertisseur en ligne gratuit de AD en MD

Markdown est couramment requis pour les fichiers README, les dépôts Git, les sites de documentation et l’édition légère, tandis que certains documents source sont fournis sous forme de fichiers AsciiDoc avec l’extension plus courte .ad. La conversion de la source préserve son contenu lisible tout en adaptant les titres, les listes, les liens, les blocs de code et les tableaux à la syntaxe Markdown.

Qu’est-ce que le format AD ?

Dans la catégorie des fichiers texte, .ad désigne couramment un fichier source AsciiDoc. AsciiDoc est un langage de balisage en texte brut destiné à la documentation technique, aux livres, aux manuels, aux fichiers README et aux pages web ; le même langage est plus souvent enregistré avec l’extension .adoc ou .asciidoc.

Les fichiers AsciiDoc peuvent être créés avec le processeur AsciiDoc d’origine, Asciidoctor, des éditeurs de texte et des systèmes de génération de documentation. Ils contiennent un balisage source lisible tel que des titres de section, des listes, des liens, des blocs de code source, des avertissements, des tableaux, des attributs et des directives include. L’extension seule ne permet pas de le confirmer, vérifiez donc que le fichier contient bien une syntaxe AsciiDoc avant de le convertir.

Qu’est-ce que le format MD ?

.md désigne un fichier Markdown. Markdown utilise des caractères en texte brut pour les titres, l’emphase, les liens, les listes, les citations, les blocs de code et les autres éléments de structure d’un document. GitHub, GitLab, les générateurs de sites statiques, les applications de prise de notes, les plateformes de documentation et les éditeurs de code affichent couramment le Markdown.

Markdown est utile lorsqu’un document doit rester facile à lire sans moteur de rendu, bien fonctionner avec le contrôle de version ou être accepté comme fichier README ou source de documentation. GitHub Flavored Markdown, couramment appelé GFM, ajoute les tableaux, les listes de tâches, le texte barré et les blocs de code délimités.

Comment convertir réellement AD en MD

Utilisation d’Asciidoctor et de Pandoc

Pour une conversion fiable, utilisez Asciidoctor pour interpréter la source AsciiDoc et produire du DocBook XML, puis utilisez Pandoc pour convertir ce fichier intermédiaire structuré en Markdown GFM. Installez Asciidoctor et Pandoc, placez la source dans le répertoire de travail, puis exécutez :

1. Convertissez le fichier AsciiDoc en DocBook XML :
   asciidoctor -b docbook5 -o input.xml input.ad
2. Convertissez le fichier XML en Markdown :
   pandoc -f docbook -t gfm input.xml -o output.md
3. Ouvrez output.md dans un éditeur Markdown et vérifiez les titres, les liens, les tableaux, les images, les listes et les blocs de code.

Pour utiliser un pipeline shell en une seule étape, exécutez :

asciidoctor -b docbook5 -o - input.ad | pandoc -f docbook -t gfm -o output.md

Utilisation du convertisseur en ligne intégré

Vous pouvez convertir gratuitement le fichier sur 101convert.com sans installer de logiciel : sélectionnez le format d’entrée AD, importez input.ad, choisissez MD comme format de sortie, démarrez la conversion, puis téléchargez le fichier .md obtenu.

Limites de qualité et de compatibilité

La conversion modifie le balisage au lieu de simplement renommer l’extension. Les attributs AsciiDoc, le contenu conditionnel, les macros, les références croisées, les diagrammes intégrés et les structures complexes de tableaux ou d’avertissements peuvent nécessiter une modification manuelle après la conversion.

Utilisez des chemins qui restent valides depuis l’emplacement du fichier Markdown. Les références aux images peuvent nécessiter une correction, et les rôles ou attributs propres à AsciiDoc peuvent être supprimés, car le Markdown standard ne possède pas d’équivalent. La sortie GFM est généralement la cible la plus compatible pour GitHub et GitLab, tandis que le Markdown de base est préférable lorsque la destination prend uniquement en charge la syntaxe d’origine.

Les directives include d’AsciiDoc et les substitutions de la source peuvent avoir une incidence sur le résultat généré. Examinez la sortie après le prétraitement, en particulier lorsque la source utilise des fichiers externes, des attributs personnalisés ou des chemins d’image relatifs.