Introdução ao Asciidoctor em Java
1. Introdução
Neste artigo, faremos uma introdução rápida sobre como usar o Asciidoctor com Java. Vamos demonstrar como gerar HTML5 ou PDF a partir de um documento AsciiDoc.
2. O que é AsciiDoc?
O AsciiDoc é um formato de documento de texto. Pode ser usado porwriting documentation, books, web pages, man pages and many other.
Por ser muito configurável, os documentos AsciiDoc podem ser convertidos em muitos outros formatos, como HTML, PDF, páginas de manual, EPUB e outros.
Como a sintaxe do AsciiDoc é bastante básica, ela se tornou muito popular com um grande suporte em vários plugins de navegador, plugins para linguagens de programação e outras ferramentas.
Para aprender mais sobre a ferramenta, sugerimos a leitura deofficial documentation, onde você pode encontrar muitos recursos úteis para aprender a sintaxe adequada e métodos para exportar seu documento AsciiDoc para outros formatos.
3. O que é Asciidoctor?
Asciidoctor é umtext processor for converting AsciiDoc documents em HTML, PDF e outros formatos. É escrito em Ruby e empacotado como um RubyGem.
Como mencionado acima, o AsciiDoc é um formato muito popular para escrever documentação, assim você pode facilmente encontrar o Asciidoctor como um pacote padrão em muitas distribuições GNU Linux como Ubuntu, Debian, Fedora e Arch.
Como queremos usar o Asciidoctor na JVM, vamos falar sobre AsciidoctorJ - que é Asciidoctor com Java.
4. Dependências
5. API AsciidoctorJ
O ponto de entrada para AsciidoctorJ é a interface JavaAsciidoctor.
Esses métodos são:
-
convert - analisa o documento AsciiDoc de umString ouStreame o converte para o tipo de formato fornecido
-
convertFile - analisa o documento AsciiDoc de um objetoFile fornecido e o converte para o tipo de formato fornecido
-
convertFiles - igual ao anterior, mas o método aceita vários objetosFile
-
convertDirectory - analisa todos os documentos AsciiDoc na pasta fornecida e os converte para o tipo de formato fornecido
5.1. Uso da API no código
Para criar uma instânciaAsciidoctor, você precisa recuperar a instância do método de fábrica fornecido:
import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
..
//some code
..
Asciidoctor asciidoctor = create();Com a instância recuperada, podemos converter o documento AsciiDoc com muita facilidade:
String output = asciidoctor
.convert("Hello _example_!", new HashMap()); Se quisermos converter um documento de texto do sistema de arquivos, usaremos o métodoconvertFile:
String output = asciidoctor
.convertFile(new File("example.adoc"), new HashMap()); Para converter vários arquivos, o métodoconvertFiles aceita o objetoList como primeiro parâmetro e retorna matrizes de objetosString. Mais interessante é como converter um diretório inteiro com AsciidoctorJ.
Como mencionado acima, para converter um diretório inteiro - devemos chamar o métodoconvertDirectory. Isso verifica o caminho fornecido e procura todos os arquivos com extensões AsciiDoc (.adoc, .ad, .asciidoc, .asc) e os converte. Para verificar todos os arquivos, uma instância deDirectoryWalker deve ser fornecida ao método.
Atualmente, o Asciidoctor fornece duas implementações internas da interface mencionada:
-
AsciiDocDirectoryWalker - converte todos os arquivos de determinada pasta e suas subpastas. Ignora todos os arquivos começando com "_"
-
GlobDirectoryWalker - converte todos os arquivos de determinada pasta seguindo uma expressão glob
String[] result = asciidoctor.convertDirectory(
new AsciiDocDirectoryWalker("src/asciidoc"),
new HashMap()); Além disso, a interfacewe can call convert method with provided java.io.Reader and java.io.Writer interfaces.Reader é usada como a fonte e a interfaceWriter é usada para gravar os dados convertidos:
FileReader reader = new FileReader(new File("sample.adoc"));
StringWriter writer = new StringWriter();
asciidoctor.convert(reader, writer, options().asMap());
StringBuffer htmlBuffer = writer.getBuffer();5.2. Geração de PDF
To generate a PDF file from an Asciidoc document, we need to specify the type of the generated file in options. Se você olhar um pouco mais cuidadosamente para os exemplos anteriores, você notará que o segundo parâmetro de qualquer método de conversão é umMap - que representa o objeto de opções.
Definiremos a opção in_place como true para que nosso arquivo seja gerado automaticamente e salvo no sistema de arquivos:
Map options = options()
.inPlace(true)
.backend("pdf")
.asMap();
String outfile = asciidoctor.convertFile(new File("example.adoc"), options); 6. Maven Plugin
Na seção anterior, mostramos como podemos gerar arquivo PDF diretamente com sua própria implementação em Java. Nesta seção, mostraremos como gerar um arquivo PDF durante a criação do Maven. Simiar plugins exist for Gradle and Ant.
Para habilitar a geração de PDF durante a construção, você precisa adicionar esta dependência ao seupom.xml:
org.asciidoctor
asciidoctor-maven-plugin
1.5.5
org.asciidoctor
asciidoctorj-pdf
1.5.0-alpha.15
A versão mais recente da dependência do plugin Maven pode ser encontradahere.
6.1. Uso
Para usar o plugin na construção, você tem que defini-lo nopom.xml:
output-html
generate-resources
process-asciidoc
Uma vez que o plug-in não é executado em nenhuma fase específica, você deve definir a fase em que deseja iniciá-lo.
Assim como no plug-in Asciidoctorj, também podemos usar várias opções para geração de PDF aqui.
Vamos dar uma olhada rápida nas opções básicas enquanto você pode encontrar outras opções emdocumentation:
-
sourceDirectory - a localização do diretório onde você tem documentos Asciidoc
-
outputDirectory - a localização do diretório onde você deseja armazenar os arquivos PDF gerados
-
backend - o tipo de saída do Asciidoctor. Para geração de PDF definido para pdf
Este é um exemplo de como definir opções básicas no plug-in:
src/main/doc
target/docs
pdf
Depois de executar a construção, os arquivos PDF podem ser encontrados no diretório de saída especificado.
7. Conclusão
Mesmo que AsciiDoc seja muito fácil de usar e entender, é uma ferramenta muito poderosa para gerenciar documentação e outros documentos.
Neste artigo, demonstramos uma maneira simples de gerar arquivos HTML e PDF a partir do documento AsciiDoc.
O código pode ser encontrado emover on GitHub.