Introduktion til Asciidoctor i Java
1. Introduktion
I denne artikel laver vi en hurtig introduktion til, hvordan du bruger Asciidoctor med Java. Vi demonstrerer, hvordan man genererer HTML5 eller PDF fra et AsciiDoc-dokument.
2. Hvad er AsciiDoc?
AsciiDoc er et tekstdokumentformat. Det kan bruges til skrivedokumentation, bøger, websider, mandsider og mange andre.
Da det er meget konfigurerbart, kan AsciiDoc-dokumenter konverteres til mange andre formater som HTML, PDF, man-sider, EPUB og andre.
Fordi AsciiDoc-syntaks er ret grundlæggende, er det blevet meget populært med en stor understøttelse i forskellige browser-plugins, plugins til programmeringssprog og andre værktøjer.
For at lære mere om værktøjet, foreslår vi at læse den officielle dokumentation, hvor du kan finde mange nyttige ressourcer til at lære korrekt syntaks og metoder til at eksportere dit AsciiDoc-dokument til andre formater.
3. Hvad er Asciidoctor?
Asciidoctor er en tekstbehandler til konvertering af AsciiDoc-dokumenter i HTML, PDF og andre formater. Den er skrevet i Ruby og pakket som en RubyGem.
Som nævnt ovenfor er AsciiDoc et meget populært format til at skrive dokumentation, så du kan nemt finde Asciidoctor som en standardpakke i mange GNU Linux-distribution som Ubuntu, Debian, Fedora og Arch.
Da vi vil bruge Asciidoctor på JVM, vil vi tale om AsciidoctorJ - som er Asciidoctor med Java.
4. Afhængigheder
For at inkludere AsciidoctorJ-pakken i vores ansøgning, følgende pom.xml adgang er nødvendig:
org.asciidoctor asciidoctorj 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 Seneste versioner af biblioteker kan findes her og her.
5. AsciidoctorJ API
Indgangsstedet for AsciidoctorJ er Asciidoctor Java-grænseflade.
Disse metoder er:
- konvertere - analyserer AsciiDoc-dokument fra en Snor eller Strøm og konverterer den til den angivne formattype
- convertFile - analyserer AsciiDoc-dokument fra en leveret Fil objekt og konverterer det til den angivne formattype
- convertFiles - samme som tidligere, men metoden accepterer flere Fil genstande
- convertDirectory - analyserer alle AsciiDoc-dokumenter i den medfølgende mappe og konverterer dem til den angivne formattype
5.1. API-brug i kode
At oprette en Asciidoctor eksempel, skal du hente forekomsten fra den angivne fabriksmetode:
importer statisk org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. // noget kode .. Asciidoctor asciidoctor = create (); Med hentet instans kan vi konvertere AsciiDoc-dokument meget let:
Strengoutput = asciidoctor .convert ("Hej _Baeldung_!", Nyt HashMap ());Hvis vi vil konvertere et tekstdokument fra filsystemet, bruger vi convertFile metode:
Strengoutput = asciidoctor .convertFile (ny fil ("baeldung.adoc"), ny HashMap ()); For at konvertere flere filer, convertFiles metode accepterer Liste objekt som en første parameter og returnerer arrays af Snor genstande.
Mere interessant er, hvordan man konverterer en hel mappe med AsciidoctorJ.
Som nævnt ovenfor skal vi kalde for at konvertere en hel mappe convertDirectory metode. Dette scanner den angivne sti og søger efter alle filer med AsciiDoc-udvidelser (.adoc, .ad, .asciidoc, .asc) og konverterer dem. For at scanne alle filer, en forekomst af DirectoryWalker skal leveres til metoden.
I øjeblikket leverer Asciidoctor to indbyggede implementeringer af den nævnte grænseflade:
- AsciiDocDirectoryWalker - konverterer alle filer i den givne mappe og dens undermapper. Ignorer alle filer startende med “_”
- GlobDirectoryWalker - konvertere alle filer i den givne mappe efter et glob-udtryk
Streng [] resultat = asciidoctor.convertDirectory (ny AsciiDocDirectoryWalker ("src / asciidoc"), ny HashMap ()); Også, vi kan kalde konvertere metode med forudsat java.io.Læser og java.io.Writer grænseflader.Læser interface bruges som kilde, og Forfatter interface bruges til at skrive konverterede data:
FileReader-læser = ny FileReader (ny fil ("sample.adoc")); StringWriter-forfatter = ny StringWriter (); asciidoctor.convert (læser, forfatter, optioner (). asMap ()); StringBuffer htmlBuffer = writer.getBuffer ();5.2. PDF-generering
For at generere en PDF-fil fra et Asciidoc-dokument skal vi angive typen af den genererede fil i indstillinger. Hvis du ser lidt mere nøje på de tidligere eksempler, vil du bemærke, at den anden parameter for enhver konverteringsmetode er en Kort - som repræsenterer option objekt.
Vi sætter indstillingen in_place til sand, så vores fil automatisk genereres og gemmes i filsystemet:
Kortmuligheder = optioner () .inPlace (sand) .backend ("pdf") .asMap (); String outfile = asciidoctor.convertFile (ny fil ("baeldung.adoc"), valgmuligheder);6. Maven-plugin
I det forrige afsnit viste vi, hvordan vi kan generere PDF-filer direkte med din egen implementering i Java. I dette afsnit viser vi, hvordan du genererer PDF-fil under Maven-build. Simiar-plugins findes til Gradle og Ant.
For at aktivere PDF-generering under opbygningen skal du tilføje denne afhængighed til din pom.xml:
org.asciidoctor asciidoctor-maven-plugin 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 Den nyeste version af Maven-pluginafhængighed kan findes her.
6.1. Anvendelse
For at bruge pluginet i build skal du definere det i pom.xml:
output-html generer-ressourcer proces-asciidoc Da pluginet ikke kører i nogen specifik fase, skal du indstille den fase, hvor du vil starte det.
Som med Asciidoctorj-pluginet kan vi også bruge forskellige muligheder for PDF-generering her.
Lad os se hurtigt på de grundlæggende muligheder, mens du kan finde andre muligheder i dokumentationen:
- sourceDirectory - placeringen af biblioteket, hvor du har Asciidoc-dokumenter
- outputDirectory - placeringen af det bibliotek, hvor du vil gemme genererede PDF-filer
- bagende - typen af output fra Asciidoctor. Til PDF-generering indstillet til pdf
Dette er et eksempel på, hvordan man definerer grundlæggende muligheder i pluginet:
src / main / doc target / docs pdf Efter at have kørt build'en kan PDF-filerne findes i det angivne outputkatalog.
7. Konklusion
Selvom AsciiDoc er meget let at bruge og forstå, er det et meget kraftfuldt værktøj til styring af dokumentation og andre dokumenter.
I denne artikel demonstrerede vi en enkel måde at generere HTML- og PDF-filer fra AsciiDoc-dokument.
Koden kan findes på over på GitHub.
