streamalism.org

1. Inleiding

In dit artikel maken we een korte inleiding over het gebruik van Asciidoctor met Java. We laten zien hoe u HTML5 of PDF genereert vanuit een AsciiDoc-document.

2. Wat is AsciiDoc?

AsciiDoc is een tekstdocumentformaat. Het kan worden gebruikt voor het schrijven van documentatie, boeken, webpagina's, manpages en vele andere.

Omdat het zeer configureerbaar is, kunnen AsciiDoc-documenten worden geconverteerd naar vele andere formaten zoals HTML, PDF, man-pagina's, EPUB en andere.

Omdat AsciiDoc-syntaxis vrij eenvoudig is, is het erg populair geworden met een grote ondersteuning in verschillende browserplug-ins, plug-ins voor programmeertalen en andere tools.

Om meer over de tool te weten te komen, raden we u aan de officiële documentatie te lezen, waar u veel nuttige bronnen kunt vinden voor het leren van de juiste syntaxis en methoden voor het exporteren van uw AsciiDoc-document naar andere formaten.

3. Wat is Asciidoctor?

Asciidoctor is een tekstverwerker voor het converteren van AsciiDoc-documenten naar HTML, PDF en andere formaten. Het is geschreven in Ruby en verpakt als een RubyGem.

Zoals hierboven vermeld, is AsciiDoc een erg populair formaat voor het schrijven van documentatie, dus je kunt Asciidoctor gemakkelijk vinden als een standaardpakket in veel GNU Linux-distributies zoals Ubuntu, Debian, Fedora en Arch.

Omdat we Asciidoctor op de JVM willen gebruiken, zullen we het hebben over AsciidoctorJ - dat is Asciidoctor met Java.

4. Afhankelijkheden

Om het AsciidoctorJ-pakket in onze applicatie op te nemen, het volgende pom.xml invoer is vereist:

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

De nieuwste versies van bibliotheken zijn hier en hier te vinden.

5. AsciidoctorJ API

Het toegangspunt voor AsciidoctorJ is het Asciidoctor Java-interface.

Die methoden zijn:

• converteren - parseert AsciiDoc-document van een Draad of Stroom en converteert het naar het opgegeven formaattype
• convertFile - parseert AsciiDoc-document van een opgegeven het dossier object en converteert het naar het opgegeven formaattype
• bestanden omzetten - hetzelfde als de vorige, maar de methode accepteert meerdere het dossier voorwerpen
• convertDirectory - parseert alle AsciiDoc-documenten in de opgegeven map en converteert ze naar het opgegeven formaattype

5.1. API-gebruik in code

Om een Asciidoctor u moet de instantie bijvoorbeeld ophalen via de opgegeven fabrieksmethode:

importeer statische org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. // een code .. Asciidoctor asciidoctor = create (); 

Met het opgehaalde exemplaar kunnen we het AsciiDoc-document heel gemakkelijk converteren:

String output = asciidoctor .convert ("Hallo _Baeldung_!", Nieuwe HashMap ());

Als we een tekstdocument uit het bestandssysteem willen converteren, gebruiken we de convertFile methode:

String output = asciidoctor .convertFile (nieuw bestand ("baeldung.adoc"), nieuwe HashMap ()); 

Voor het converteren van meerdere bestanden, de bestanden omzetten methode accepteert Lijst object als een eerste parameter en retourneert arrays van Draad voorwerpen.

Interessanter is hoe je een hele directory converteert met AsciidoctorJ.

Zoals hierboven vermeld, moeten we om een ​​hele directory te converteren de convertDirectory methode. Dit scant het opgegeven pad en zoekt naar alle bestanden met AsciiDoc-extensies (.adoc, .ad, .asciidoc, .asc) en converteert ze. Om alle bestanden te scannen, moet een instantie van het DirectoryWalker moet aan de methode worden verstrekt.

Momenteel biedt Asciidoctor twee ingebouwde implementaties van de genoemde interface:

• AsciiDocDirectoryWalker - converteert alle bestanden van de gegeven map en zijn submappen. Negeert alle bestanden die beginnen met "_"
• GlobDirectoryWalker - converteer alle bestanden van een bepaalde map volgens een glob-uitdrukking

String [] resultaat = asciidoctor.convertDirectory (nieuwe AsciiDocDirectoryWalker ("src / asciidoc"), nieuwe HashMap ()); 

Ook, we kunnen de conversiemethode noemen met het opgegeven java.io.Reader en java.io.Writer interfaces.Lezer interface wordt gebruikt als de bron, en auteur interface wordt gebruikt voor het schrijven van geconverteerde gegevens:

FileReader-lezer = nieuwe FileReader (nieuw bestand ("sample.adoc")); StringWriter-schrijver = nieuwe StringWriter (); asciidoctor.convert (lezer, schrijver, opties (). asMap ()); StringBuffer htmlBuffer = writer.getBuffer ();

5.2. PDF-generatie

Om een ​​PDF-bestand van een Asciidoc-document te genereren, moeten we het type van het gegenereerde bestand specificeren in de opties. Als je wat nauwkeuriger naar de vorige voorbeelden kijkt, zul je merken dat de tweede parameter van elke conversiemethode een Kaart - wat optiesobject vertegenwoordigt.

We stellen de optie in_place in op true, zodat ons bestand automatisch wordt gegenereerd en opgeslagen in het bestandssysteem:

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

6. Maven-plug-in

In de vorige sectie hebben we laten zien hoe we direct een PDF-bestand kunnen genereren met uw eigen implementatie in Java. In dit gedeelte laten we zien hoe u een PDF-bestand genereert tijdens het bouwen van Maven. Er bestaan ​​soortgelijke plug-ins voor Gradle en Ant.

Om het genereren van PDF tijdens het bouwen mogelijk te maken, moet u deze afhankelijkheid toevoegen aan uw pom.xml:

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

De nieuwste versie van de afhankelijkheid van de Maven-plug-in vindt u hier.

6.1. Gebruik

Om de plug-in in de build te gebruiken, moet u deze definiëren in het pom.xml:

   output-html bronnen genereren proces-asciidoc 

Omdat de plug-in niet in een specifieke fase wordt uitgevoerd, moet u de fase instellen waarin u deze wilt starten.

Net als bij de Asciidoctorj-plug-in, kunnen we hier ook verschillende opties gebruiken voor het genereren van PDF's.

Laten we de basisopties snel bekijken, terwijl u andere opties in de documentatie kunt vinden:

• sourceDirectory - de locatie van de directory waar u Asciidoc-documenten hebt
• outputDirectory - de locatie van de directory waar u gegenereerde PDF-bestanden wilt opslaan
• backend - het type output van Asciidoctor. Voor het genereren van PDF-bestanden voor pdf

Dit is een voorbeeld van hoe u basisopties in de plug-in definieert:

  src / main / doc target / docs pdf 

Na het uitvoeren van de build zijn de PDF-bestanden te vinden in de opgegeven uitvoermap.

7. Conclusie

Hoewel AsciiDoc heel gemakkelijk te gebruiken en te begrijpen is, is het een zeer krachtige tool voor het beheren van documentatie en andere documenten.

In dit artikel hebben we een eenvoudige manier gedemonstreerd om HTML- en PDF-bestanden te genereren vanuit een AsciiDoc-document.

De code is te vinden op meer dan op GitHub.