Convertitore online gratuito da ASCIIDOC a MD

GitHub, GitLab e molti strumenti per la documentazione accettano Markdown ma non AsciiDoc, quindi potrebbe essere necessario convertire un file .adoc prima di pubblicarlo o modificarlo in tali ambienti. La conversione in .md conserva il codice sorgente leggibile, adattando al contempo titoli, elenchi, collegamenti e blocchi di codice alla sintassi Markdown.

Cos'è il formato ASCIIDOC

AsciiDoc è un formato di markup in testo semplice utilizzato per la documentazione software, i manuali, i libri, le note di rilascio e i file README. Le estensioni comuni includono .adoc, .asciidoc e .ad.

I file AsciiDoc vengono comunemente creati o elaborati con Asciidoctor, l'implementazione moderna in Ruby, oppure con il processore AsciiDoc precedente. Anche editor come Visual Studio Code, IntelliJ IDEA e strumenti dedicati alla documentazione possono creare questi file, poiché il codice sorgente è costituito da testo normale.

AsciiDoc supporta attributi, direttive include, blocchi di avviso, tabelle, riferimenti incrociati, diagrammi, citazioni e strutture di documenti riutilizzabili. Alcune di queste funzionalità non hanno un equivalente diretto in Markdown.

Cos'è il formato MD

MD è l'estensione abituale dei file Markdown. Markdown è un formato di testo semplice e leggero, progettato per offrire un codice sorgente leggibile e una facile conversione in HTML. GitHub, GitLab, Bitbucket, generatori di siti statici, wiki, applicazioni per prendere appunti ed editor di codice lo supportano comunemente.

Markdown è una scelta pratica quando un repository richiede un README.md, quando i collaboratori modificano la documentazione con strumenti orientati a Markdown o quando i file sorgente devono essere visualizzati in modo coerente sulle piattaforme di hosting del codice. GitHub Flavored Markdown (GFM) aggiunge tabelle, elenchi di attività, collegamenti automatici e blocchi di codice delimitati.

Come convertire effettivamente ASCIIDOC in MD

Per una conversione locale, installare Pandoc, quindi eseguire:

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

Sostituire input.adoc con il nome del file sorgente e output.md con la destinazione desiderata. L'opzione -f asciidoc seleziona il lettore AsciiDoc, -t gfm produce GitHub Flavored Markdown e -o scrive il risultato in un file.

Per convertire un file con estensione .asciidoc, utilizzare il nome effettivo:

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

Se la versione installata di Pandoc non fornisce un lettore AsciiDoc, utilizzare Asciidoctor per creare prima un file DocBook XML, quindi convertire il file intermedio:

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

Per un'opzione che non richiede installazione, caricare il file sorgente su 101convert.com, scegliere Markdown come formato di output, avviare la conversione e scaricare il file .md risultante. Evitare di caricare documenti contenenti informazioni riservate o soggette a restrizioni.

Limiti di qualità e compatibilità

La conversione non è sempre priva di perdite. Gli attributi AsciiDoc, i contenuti condizionali, gli include, i ruoli personalizzati, le macro, le estensioni, le tabelle complesse, i blocchi di avviso e i riferimenti incrociati possono essere semplificati, omessi o prodotti come markup non elaborato.

Controllare il Markdown generato per verificare i livelli dei titoli, l'annidamento degli elenchi, la formattazione delle tabelle, i percorsi delle immagini, i delimitatori dei blocchi di codice, i collegamenti e i caratteri preceduti da escape. GFM supporta tabelle ed elenchi di attività, ma altri parser Markdown potrebbero visualizzare queste funzionalità in modo diverso.

Gli include di AsciiDoc potrebbero richiedere una pre-elaborazione prima della conversione. Risolvere i file a cui fanno riferimento le direttive include:: e verificare che i percorsi relativi delle immagini e dei collegamenti puntino ancora alle posizioni corrette dopo lo spostamento del file di output.