Conversor online gratuito de ASCIIDOC para HTML

Os arquivos AsciiDoc precisam ser convertidos quando a documentação deve ser aberta em um navegador da web, publicada em um site ou fornecida a um sistema que aceita HTML em vez do código-fonte de marcação. O HTML preserva títulos, listas, links, tabelas, blocos de código e outras estruturas em um formato diretamente visualizável.

O que é o formato ASCIIDOC

AsciiDoc é um formato de marcação em texto simples para documentos estruturados, como documentação de software, manuais, arquivos README, artigos e especificações técnicas. Os autores marcam a estrutura usando uma sintaxe legível para títulos, listas, links, avisos, tabelas, código-fonte, imagens e referências cruzadas.

As extensões de nome de arquivo comuns são .adoc, .asciidoc e, às vezes, .asc. Os arquivos são criados ou editados com editores de texto comuns e ferramentas de documentação, incluindo Asciidoctor, Asciidoctor.js e Antora. Um arquivo AsciiDoc é código-fonte de marcação, portanto, um navegador exibirá seus caracteres de formatação em vez de renderizar a estrutura pretendida do documento.

O que é o formato HTML

HTML é o formato de marcação interpretado pelos navegadores da web e usado por sites, portais de documentação, sistemas de gerenciamento de conteúdo e fluxos de trabalho relacionados a e-mail. Uma conversão para HTML transforma a estrutura do AsciiDoc em elementos como <h1>, <p>, <ul>, <table> e <pre>.

O HTML é adequado quando os destinatários precisam visualizar o conteúdo em um navegador, pesquisar a documentação, copiar o conteúdo ou usar um arquivo que possa ser incorporado a uma página da web. O resultado pode incluir estilos CSS, referências a imagens, recursos de destaque de sintaxe e links para outras páginas geradas.

Como converter ASCIIDOC em HTML de fato

Usando o Asciidoctor

1. Instale o Ruby e o processador Asciidoctor e execute gem install asciidoctor.
2. Abra um terminal no diretório que contém o arquivo de origem.
3. Converta-o com asciidoctor input.adoc -o output.html. Substitua os nomes de arquivo pelos nomes reais da origem e do destino.
4. Abra output.html em um navegador e verifique os títulos, links, tabelas, blocos de código e imagens.

Para produzir HTML incorporado adequado para inserção em outra página, use asciidoctor -e input.adoc -o fragment.html. Para aplicar uma folha de estilos, forneça sua localização com um atributo do Asciidoctor, como asciidoctor -a stylesheet=site.css input.adoc -o output.html.

Usando um conversor online

Você pode converter o arquivo gratuitamente no site 101convert.com sem instalar software. Carregue o arquivo AsciiDoc, escolha HTML como formato de saída, se necessário, inicie a conversão e baixe o arquivo gerado. Verifique as imagens vinculadas e os arquivos incluídos após o download, pois a conversão baseada em navegador pode não ter acesso aos caminhos locais referenciados pela origem.

Considerações sobre qualidade e compatibilidade

Os documentos AsciiDoc podem referenciar imagens, incluir outros arquivos de origem, carregar atributos e usar extensões personalizadas. Uma conversão local com o Asciidoctor geralmente é preferível quando essas dependências são importantes, pois o conversor pode ser executado a partir do diretório correto do projeto e usar os atributos pretendidos.

Mantenha as imagens referenciadas e os arquivos CSS nos locais relativos esperados ou atualize os caminhos gerados antes da publicação. Um arquivo HTML pode conter links para recursos separados em vez de incorporá-los, portanto, mover apenas o arquivo HTML pode causar imagens ausentes ou uma saída sem estilos.

Macros personalizadas, extensões não compatíveis, inclusões ausentes e atributos incorretos do documento podem produzir uma saída incompleta. Teste o HTML gerado no navegador ou sistema de publicação de destino, especialmente quando a origem usa destaque de sintaxe, links entre documentos ou caracteres não ASCII.