Conversor online gratuito de ASCIIDOC para EPUB

Leitores de e-books e sistemas de publicação geralmente exigem EPUB em vez de um arquivo-fonte AsciiDoc. A conversão preserva seus títulos, parágrafos, listas, links, imagens e outros conteúdos estruturados em um formato de fluxo adaptável que os leitores podem abrir em telefones, tablets e dispositivos dedicados para e-books.

O que é o formato ASCIIDOC

AsciiDoc é um formato de marcação de texto simples para documentos estruturados, como livros, manuais, documentação de software, artigos e arquivos README. Os autores escrevem títulos, listas, tabelas, links, blocos de código, atributos, referências cruzadas e advertências usando uma sintaxe de texto legível, em vez de editar um documento binário.

As extensões de origem comuns incluem .adoc, .asciidoc e .asc. Asciidoctor e Asciidoc usam esses arquivos para gerar HTML, PDF, páginas man e documentos EPUB. Os desenvolvedores geralmente os encontram em repositórios de documentação, projetos de sites estáticos, projetos baseados em Git e sistemas de compilação de documentação.

O que é o formato EPUB

EPUB é um pacote de e-book baseado em ZIP que contém conteúdo XHTML, folhas de estilo CSS, metadados, arquivos de navegação e, opcionalmente, imagens, fontes e outros recursos. O EPUB 3 é compatível com HTML semântico, layouts responsivos, navegação, áudio ou vídeo e escrita da direita para a esquerda ou vertical, quando o sistema de leitura oferece suporte a esses recursos.

Ao contrário de um PDF com páginas fixas, o conteúdo EPUB se adapta ao tamanho da tela, às configurações de fonte e à orientação do dispositivo de leitura. Ele é adequado para distribuir documentação extensa ou livros por meio de leitores de e-books e bibliotecas, além de verificar o resultado com aplicativos compatíveis com EPUB.

Como converter ASCIIDOC para EPUB

Use o Asciidoctor EPUB3

Asciidoctor EPUB3 é a opção mais direta porque entende construções específicas do AsciiDoc, em vez de tratar a origem como uma marcação genérica. Instale o Ruby primeiro, caso ainda não esteja disponível, e instale o conversor:

gem install asciidoctor-epub3

No diretório que contém o arquivo de origem, execute:

asciidoctor-epub3 book.adoc -o book.epub

Substitua book.adoc pelo nome de arquivo real. O conversor lê o cabeçalho do documento, os arquivos incluídos, as imagens referenciadas, os atributos e os elementos estruturais, e então grava book.epub.

Para um projeto com vários arquivos, mantenha as origens incluídas e os diretórios de imagens nos locais relativos esperados. Um comando típico com um diretório de trabalho personalizado é:

asciidoctor-epub3 -D output book.adoc

Defina os metadados do documento no cabeçalho do AsciiDoc antes da conversão, por exemplo:

= Book title
Author Name <author@example.com>
:revnumber: 1.0
:description: A short description
:doctype: book
:toc:
:sectnums:

Use um atributo de imagem, como :imagesdir: images, quando os caminhos das imagens forem relativos a um diretório comum. Verifique se todas as imagens referenciadas existem e usam um formato compatível com os sistemas de leitura de destino, normalmente JPEG, PNG ou SVG.

Converta sem instalar software

Você pode converter o arquivo gratuitamente no site 101convert.com quando não for prático instalar Ruby ou Asciidoctor. Envie o arquivo AsciiDoc, escolha EPUB como formato de saída, inicie a conversão e baixe o e-book gerado.

Use o Pandoc como alternativa

O Pandoc pode converter alguns documentos AsciiDoc diretamente:

pandoc book.adoc -o book.epub

Use o Pandoc para documentos relativamente simples ou quando ele já fizer parte do fluxo de trabalho de publicação. O Asciidoctor EPUB3 geralmente preserva com mais confiabilidade os atributos específicos do AsciiDoc, as advertências, os includes e as referências cruzadas.

Qualidade, compatibilidade e limitações

EPUB é um formato de fluxo adaptável, portanto quebras de linha fixas, posições exatas de página e instruções de layout no estilo PDF não podem ser preservadas de maneira consistente. Números de página, viúvas, controle de órfãs e quebra de linha variam conforme o sistema de leitura e as configurações de fonte do usuário.

Extensões complexas do AsciiDoc, conversores personalizados, diagramas incorporados, macros não compatíveis e formatação exclusiva de PDF podem exigir ajustes manuais. Gere os arquivos de diagramas antes da conversão e use caminhos relativos para todos os recursos locais.

Abra o resultado em pelo menos um leitor de EPUB e inspecione o índice, a hierarquia de títulos, os links, os blocos de código, as tabelas, as imagens e os caracteres especiais. Para validação no nível do pacote, execute o EPUBCheck:

epubcheck book.epub

Corrija recursos ausentes, XHTML inválido, erros de metadados e avisos de navegação antes de distribuir o arquivo.