Conversor online gratuito de ASCIIDOC para MD

GitHub, GitLab e muitas ferramentas de documentação aceitam Markdown, mas não AsciiDoc, portanto um arquivo .adoc pode precisar ser convertido antes de ser publicado ou editado nesses locais. Convertê-lo para .md preserva o código-fonte legível, ao mesmo tempo que adapta títulos, listas, links e blocos de código à sintaxe Markdown.

O que é o formato ASCIIDOC

AsciiDoc é um formato de marcação de texto simples usado para documentação de software, manuais, livros, notas de versão e arquivos README. As extensões comuns incluem .adoc, .asciidoc e .ad.

Os arquivos AsciiDoc são normalmente criados ou processados com Asciidoctor, a implementação moderna em Ruby, ou com o processador AsciiDoc mais antigo. Editores como Visual Studio Code, IntelliJ IDEA e ferramentas de documentação dedicadas também podem criar esses arquivos, pois o código-fonte é texto comum.

AsciiDoc oferece suporte a atributos, diretivas include, blocos de advertência, tabelas, referências cruzadas, diagramas, citações e estruturas de documentos reutilizáveis. Alguns desses recursos não têm um equivalente direto em Markdown.

O que é o formato MD

MD é a extensão usual para arquivos Markdown. Markdown é um formato leve de texto simples, desenvolvido para oferecer código-fonte legível e renderização fácil como HTML. GitHub, GitLab, Bitbucket, geradores de sites estáticos, wikis, aplicativos de anotações e editores de código geralmente oferecem suporte a ele.

Markdown é um destino prático quando um repositório exige um README.md, quando os colaboradores editam a documentação em ferramentas voltadas para Markdown ou quando os arquivos-fonte precisam ser exibidos de forma consistente em diferentes plataformas de hospedagem de código. GitHub Flavored Markdown (GFM) adiciona tabelas, listas de tarefas, autolinks e blocos de código delimitados.

Como converter ASCIIDOC para MD de fato

Para uma conversão local, instale o Pandoc e execute:

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

Substitua input.adoc pelo nome do arquivo-fonte e output.md pelo destino desejado. A opção -f asciidoc seleciona o leitor AsciiDoc, -t gfm produz GitHub Flavored Markdown e -o grava o resultado em um arquivo.

Para converter um arquivo com a extensão .asciidoc, use o nome real do arquivo:

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

Se a versão instalada do Pandoc não oferecer um leitor AsciiDoc, use Asciidoctor para criar primeiro um XML DocBook e, em seguida, converta esse arquivo intermediário:

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

Para uma opção sem instalação, envie o arquivo-fonte para 101convert.com, escolha Markdown como formato de saída, inicie a conversão e baixe o arquivo .md resultante. Evite enviar documentos que contenham informações confidenciais ou restritas.

Limites de qualidade e compatibilidade

A conversão nem sempre é sem perdas. Atributos AsciiDoc, conteúdo condicional, includes, funções personalizadas, macros, extensões, tabelas complexas, advertências e referências cruzadas podem ser simplificados, omitidos ou emitidos como markup bruto.

Inspecione o Markdown gerado quanto aos níveis dos títulos, ao aninhamento das listas, à formatação das tabelas, aos caminhos das imagens, aos blocos de código delimitados, aos links e aos caracteres escapados. GFM oferece suporte a tabelas e listas de tarefas, mas outros analisadores Markdown podem renderizar esses recursos de forma diferente.

Os includes do AsciiDoc podem exigir pré-processamento antes da conversão. Resolva os arquivos referenciados pelas diretivas include:: e verifique se os caminhos relativos de imagens e links ainda apontam para os locais corretos depois que o arquivo de saída for movido.