streamalism.org

1. Introduksjon

I denne artikkelen vil vi lage en rask introduksjon om hvordan du bruker Asciidoctor med Java. Vi demonstrerer hvordan du genererer HTML5 eller PDF fra et AsciiDoc-dokument.

2. Hva er AsciiDoc?

AsciiDoc er et tekstdokumentformat. Den kan brukes til skrivedokumentasjon, bøker, websider, man-sider og mange andre.

Siden det er veldig konfigurerbart, kan AsciiDoc-dokumenter konverteres til mange andre formater som HTML, PDF, man-sider, EPUB og andre.

Fordi AsciiDoc-syntaksen er ganske grunnleggende, har den blitt veldig populær med stor støtte i forskjellige nettleser-plugins, plugins for programmeringsspråk og andre verktøy.

For å lære mer om verktøyet, foreslår vi at du leser den offisielle dokumentasjonen der du kan finne mange nyttige ressurser for å lære riktig syntaks og metoder for å eksportere AsciiDoc-dokumentet til andre formater.

3. Hva er Asciidoctor?

Asciidoctor er en tekstbehandler for konvertering av AsciiDoc-dokumenter i HTML, PDF og andre formater. Den er skrevet i Ruby og pakket som en RubyGem.

Som nevnt ovenfor er AsciiDoc et veldig populært format for å skrive dokumentasjon, slik at du enkelt kan finne Asciidoctor som en standardpakke i mange GNU Linux-distribusjoner som Ubuntu, Debian, Fedora og Arch.

Siden vi vil bruke Asciidoctor på JVM, snakker vi om AsciidoctorJ - som er Asciidoctor med Java.

4. Avhengigheter

For å inkludere AsciidoctorJ-pakken i søknaden vår, følgende pom.xml oppføring er nødvendig:

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

Siste versjoner av biblioteker finner du her og her.

5. AsciidoctorJ API

Inngangspunktet for AsciidoctorJ er Asciidoctor Java-grensesnitt.

Disse metodene er:

• konvertere - analyserer AsciiDoc-dokument fra en String eller Strøm og konverterer den til den angitte formattypen
• convertFile - analyserer AsciiDoc-dokument fra et gitt Fil objektet og konverterer det til den angitte formattypen
• convertFiles - samme som forrige, men metoden godtar flere Fil gjenstander
• convertDirectory - analyserer alle AsciiDoc-dokumenter i den medfølgende mappen og konverterer dem til den angitte formattypen

5.1. API-bruk i kode

Å lage en Asciidoctor for eksempel må du hente forekomsten fra den angitte fabrikkmetoden:

importer statisk org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. // litt kode .. Asciidoctor asciidoctor = create (); 

Med hentet forekomst kan vi konvertere AsciiDoc-dokument veldig enkelt:

Strengutgang = asciidoctor .convert ("Hei _Baeldung_!", Ny HashMap ());

Hvis vi vil konvertere et tekstdokument fra filsystemet, bruker vi convertFile metode:

Strengutgang = asciidoctor .convertFile (ny fil ("baeldung.adoc"), ny HashMap ()); 

For å konvertere flere filer, convertFiles metoden godtar Liste objekt som første parameter og returnerer matriser av String gjenstander.

Mer interessant er hvordan du konverterer en hel katalog med AsciidoctorJ.

Som nevnt ovenfor, for å konvertere en hel katalog - bør vi kalle convertDirectory metode. Dette skanner den angitte banen og søker etter alle filer med AsciiDoc-utvidelser (.adoc, .ad, .asciidoc, .asc) og konverterer dem. For å skanne alle filene, en forekomst av DirectoryWalker bør gis til metoden.

Foreløpig tilbyr Asciidoctor to innebygde implementeringer av nevnte grensesnitt:

• AsciiDocDirectoryWalker - konverterer alle filer i gitt mappe og undermapper. Ignorer alle filer som begynner med “_”
• GlobDirectoryWalker - konvertere alle filer i gitt mappe etter et globuttrykk

Streng [] resultat = asciidoctor.convertDirectory (ny AsciiDocDirectoryWalker ("src / asciidoc"), ny HashMap ()); 

Også, vi kan kalle konvertere metoden med gitt java.io. leser og java.io.Writer grensesnitt.Leser grensesnitt brukes som kilde, og Forfatter grensesnitt brukes til å skrive konverterte data:

FileReader reader = ny FileReader (ny fil ("sample.adoc")); StringWriter-forfatter = ny StringWriter (); asciidoctor.convert (leser, forfatter, alternativer (). asMap ()); StringBuffer htmlBuffer = writer.getBuffer ();

5.2. PDF-generasjon

For å generere en PDF-fil fra et Asciidoc-dokument, må vi spesifisere typen generert fil i alternativene. Hvis du ser litt mer nøye på de forrige eksemplene, vil du legge merke til at den andre parameteren for en hvilken som helst konverteringsmetode er en Kart - som representerer alternativobjekt.

Vi setter alternativet in_place til sant slik at filen vår genereres automatisk og lagres i filsystemet:

Kartalternativer = alternativer () .inPlace (true) .backend ("pdf") .asMap (); String outfile = asciidoctor.convertFile (ny fil ("baeldung.adoc"), alternativer);

6. Maven-plugin

I forrige avsnitt viste vi hvordan vi kan generere PDF-filer direkte med din egen implementering i Java. I denne delen vil vi vise hvordan du genererer PDF-filer under Maven-bygging. Simiar-plugins finnes for Gradle og Ant.

For å aktivere PDF-generering under byggingen, må du legge til denne avhengigheten til din pom.xml:

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

Den siste versjonen av Maven plugin-avhengighet finner du her.

6.1. Bruk

For å bruke pluginet i build, må du definere det i pom.xml:

   output-html generere-ressurser prosess-asciidoc 

Siden pluginet ikke kjører i noen spesifikk fase, må du stille fasen der du vil starte den.

Som med Asciidoctorj-pluginet, kan vi også bruke forskjellige alternativer for PDF-generering her.

La oss se raskt på de grunnleggende alternativene mens du finner andre alternativer i dokumentasjonen:

• sourceDirectory - plasseringen til katalogen der du har Asciidoc-dokumenter
• outputDirectory - plasseringen til katalogen der du vil lagre genererte PDF-filer
• baksiden - typen output fra Asciidoctor. For PDF-generasjon sett for pdf

Dette er et eksempel på hvordan du definerer grunnleggende alternativer i pluginet:

  src / main / doc target / docs pdf 

Etter at du har kjørt builden, finner du PDF-filene i den angitte utdatakatalogen.

7. Konklusjon

Selv om AsciiDoc er veldig enkel å bruke og forstå, er det et veldig kraftig verktøy for å administrere dokumentasjon og andre dokumenter.

I denne artikkelen demonstrerte vi en enkel måte å generere HTML- og PDF-filer fra AsciiDoc-dokumentet.

Koden finnes på over på GitHub.