Introduzione ad Asciidoctor in Java

1. Introduzione

In questo articolo, faremo una rapida introduzione su come utilizzare Asciidoctor con Java. Dimostreremo come generare HTML5 o PDF da un documento AsciiDoc.

2. Che cos'è AsciiDoc?

AsciiDoc è un formato di documento di testo. Può essere usato per scrivere documentazione, libri, pagine web, pagine man e molti altri.

Poiché è molto configurabile, i documenti AsciiDoc possono essere convertiti in molti altri formati come HTML, PDF, pagine man, EPUB e altri.

Poiché la sintassi di AsciiDoc è piuttosto semplice, è diventata molto popolare con un ampio supporto in vari plugin per browser, plugin per linguaggi di programmazione e altri strumenti.

Per saperne di più sullo strumento, ti suggeriamo di leggere la documentazione ufficiale dove puoi trovare molte risorse utili per imparare la sintassi corretta e metodi per esportare il tuo documento AsciiDoc in altri formati.

3. Che cos'è Asciidoctor?

Asciidoctor è un elaboratore di testi per convertire documenti AsciiDoc in HTML, PDF e altri formati. È scritto in Ruby e confezionato come RubyGem.

Come accennato in precedenza, AsciiDoc è un formato molto popolare per la scrittura di documentazione, quindi puoi facilmente trovare Asciidoctor come pacchetto standard in molte distribuzioni GNU Linux come Ubuntu, Debian, Fedora e Arch.

Dato che vogliamo usare Asciidoctor sulla JVM, parleremo di AsciidoctorJ, che è Asciidoctor con Java.

4. Dipendenze

Per includere il pacchetto AsciidoctorJ nella nostra applicazione, è necessaria la seguente voce pom.xml :

 org.asciidoctor asciidoctorj 1.5.5   org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 

Le ultime versioni delle librerie possono essere trovate qui e qui.

5. AsciidoctorJ API

Il punto di ingresso per AsciidoctorJ è l' interfaccia Java di Asciidoctor .

Questi metodi sono:

  • convert - analizza il documento AsciiDoc da una stringa o da un flusso e lo converte nel tipo di formato fornito
  • convertFile - analizza il documento AsciiDoc da un oggetto File fornito e lo converte nel tipo di formato fornito
  • convertFiles - uguale al precedente, ma il metodo accetta più oggetti File
  • convertDirectory - analizza tutti i documenti AsciiDoc nella cartella fornita e li converte nel tipo di formato fornito

5.1. Utilizzo dell'API nel codice

Per creare un'istanza di Asciidoctor , è necessario recuperare l'istanza dal metodo di fabbrica fornito:

import static org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. //some code .. Asciidoctor asciidoctor = create(); 

Con l'istanza recuperata, possiamo convertire molto facilmente il documento AsciiDoc:

String output = asciidoctor .convert("Hello _Baeldung_!", new HashMap());

Se vogliamo convertire un documento di testo dal file system, useremo il metodo convertFile :

String output = asciidoctor .convertFile(new File("baeldung.adoc"), new HashMap()); 

Per convertire più file, il metodo convertFiles accetta l' oggetto List come primo parametro e restituisce array di oggetti String .

Più interessante è come convertire un'intera directory con AsciidoctorJ.

Come accennato in precedenza, per convertire un'intera directory, dovremmo chiamare il metodo convertDirectory . Questo analizza il percorso fornito e cerca tutti i file con estensioni AsciiDoc (.adoc, .ad, .asciidoc, .asc) e li converte. Per eseguire la scansione di tutti i file, è necessario fornire al metodo un'istanza di DirectoryWalker .

Attualmente, Asciidoctor fornisce due implementazioni integrate dell'interfaccia citata:

  • AsciiDocDirectoryWalker : converte tutti i file di una determinata cartella e delle sue sottocartelle. Ignora tutti i file che iniziano con "_"
  • GlobDirectoryWalker : converte tutti i file di una determinata cartella seguendo un'espressione glob
String[] result = asciidoctor.convertDirectory( new AsciiDocDirectoryWalker("src/asciidoc"), new HashMap()); 

Inoltre, possiamo chiamare il metodo convert con le interfacce java.io.Reader e java.io.Writer fornite . L' interfaccia Reader viene utilizzata come origine e l' interfaccia Writer viene utilizzata per scrivere i dati convertiti:

FileReader reader = new FileReader(new File("sample.adoc")); StringWriter writer = new StringWriter(); asciidoctor.convert(reader, writer, options().asMap()); StringBuffer htmlBuffer = writer.getBuffer();

5.2. Generazione PDF

Per generare un file PDF da un documento Asciidoc, dobbiamo specificare il tipo di file generato nelle opzioni. Se guardi un po 'più attentamente negli esempi precedenti, noterai che il secondo parametro di qualsiasi metodo di conversione è una mappa , che rappresenta l'oggetto opzioni.

Imposteremo l'opzione in_place su true in modo che il nostro file venga automaticamente generato e salvato nel file system:

Map options = options() .inPlace(true) .backend("pdf") .asMap(); String outfile = asciidoctor.convertFile(new File("baeldung.adoc"), options);

6. Plugin Maven

Nella sezione precedente, abbiamo mostrato come possiamo generare file PDF direttamente con la tua implementazione in Java. In questa sezione, mostreremo come generare file PDF durante la compilazione di Maven. Esistono plugin simili per Gradle e Ant.

Per abilitare la generazione di PDF durante la compilazione, devi aggiungere questa dipendenza al tuo pom.xml:

 org.asciidoctor asciidoctor-maven-plugin 1.5.5   org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15   

L'ultima versione della dipendenza del plugin Maven può essere trovata qui.

6.1. Utilizzo

Per utilizzare il plugin nella build, devi definirlo nel pom.xml:

   output-html generate-resources  process-asciidoc    

Poiché il plug-in non viene eseguito in una fase specifica, è necessario impostare la fase in cui si desidera avviarlo.

Come con il plugin Asciidoctorj, anche qui possiamo utilizzare varie opzioni per la generazione di PDF.

Diamo una rapida occhiata alle opzioni di base mentre puoi trovare altre opzioni nella documentazione:

  • sourceDirectory - la posizione della directory in cui sono presenti i documenti Asciidoc
  • outputDirectory - la posizione della directory in cui si desidera archiviare i file PDF generati
  • backend - il tipo di output da Asciidoctor. Per la generazione di PDF impostato per pdf

Questo è un esempio di come definire le opzioni di base nel plugin:

  src/main/doc target/docs pdf  

Dopo aver eseguito la build, i file PDF possono essere trovati nella directory di output specificata.

7. Conclusione

Anche se AsciiDoc è molto facile da usare e da capire, è uno strumento molto potente per la gestione della documentazione e di altri documenti.

In questo articolo, abbiamo dimostrato un modo semplice per generare file HTML e PDF dal documento AsciiDoc.

Il codice può essere trovato su GitHub.