Uvod u Asciidoctor u Javi

1. Uvod

U ovom ćemo članku napraviti kratki uvod o tome kako koristiti Asciidoctor s Javom. Pokazat ćemo kako generirati HTML5 ili PDF iz AsciiDoc dokumenta.

2. Što je AsciiDoc?

AsciiDoc je format tekstualnog dokumenta. Može se koristiti za pisanje dokumentacije, knjiga, web stranica, man stranica i mnogih drugih.

Budući da je vrlo konfigurabilan, AsciiDoc dokumenti mogu se pretvoriti u mnoge druge formate poput HTML-a, PDF-a, man stranica, EPUB-a i drugih.

Budući da je sintaksa AsciiDoc prilično osnovna, postala je vrlo popularna s velikom podrškom u raznim dodacima za preglednike, dodacima za programske jezike i drugim alatima.

Da biste saznali više o alatu, predlažemo da pročitate službenu dokumentaciju u kojoj možete pronaći mnoge korisne resurse za učenje pravilne sintakse i metode za izvoz vašeg AsciiDoc dokumenta u druge formate.

3. Što je asciidoctor?

Asciidoctor je procesor teksta za pretvaranje AsciiDoc dokumenata u HTML, PDF i druge formate. Napisano je na Ruby i pakirano kao RubyGem.

Kao što je gore spomenuto, AsciiDoc je vrlo popularan format za pisanje dokumentacije, tako da možete lako pronaći Asciidoctor kao standardni paket u mnogim GNU Linux distribucijama kao što su Ubuntu, Debian, Fedora i Arch.

Budući da želimo koristiti Asciidoctor na JVM, razgovarat ćemo o AsciidoctorJ - a to je Asciidoctor s Javom.

4. Ovisnosti

Da bismo u našu aplikaciju uključili paket AsciidoctorJ, slijedi sljedeće pom.xml potreban je unos:

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

Najnovije verzije knjižnica možete pronaći ovdje i ovdje.

5. API AsciidoctorJ

Ulazna točka za AsciidoctorJ je Asciidoktor Java sučelje.

Te su metode:

  • Pretvoriti - raščlanjuje dokument AsciiDoc iz a Niz ili Stream i pretvara ga u predviđeni tip formata
  • convertFile - raščlanjuje AsciiDoc dokument iz priloženog Datoteka objekt i pretvara ga u predviđeni tip formata
  • convertFiles - isto kao i prethodna, ali metoda prihvaća više njih Datoteka predmeta
  • convertDirectory - raščlanjuje sve AsciiDoc dokumente u datoj mapi i pretvara ih u predviđeni tip formata

5.1. Upotreba API-ja u kodu

Da biste stvorili Asciidoktor instancu, morate dohvatiti instancu iz ponuđene tvorničke metode:

uvesti statički org.asciidoctor.Asciidoctor.Factory.create; uvoz org.asciidoctor.Asciidoctor; .. // neki kod .. Asciidoctor asciidoctor = create (); 

Uz dohvaćenu instancu možemo vrlo lako pretvoriti AsciiDoc dokument:

Izlaz niza = asciidoctor .convert ("Pozdrav _Baeldung_!", Nova HashMap ());

Ako želimo pretvoriti tekstualni dokument iz datotečnog sustava, upotrijebit ćemo convertFile metoda:

Izlaz niza = asciidoctor .convertFile (nova datoteka ("baeldung.adoc"), nova HashMap ()); 

Za pretvaranje više datoteka, convertFiles metoda prihvaća Popis objekt kao prvi parametar i vraća nizove od Niz predmeta.

Zanimljivije je kako pretvoriti cijeli direktorij s AsciidoctorJ.

Kao što je gore spomenuto, za pretvorbu cijelog direktorija - trebali bismo nazvati convertDirectory metoda. Ovo skenira pruženi put i traži sve datoteke s nastavcima AsciiDoc (.adoc, .ad, .asciidoc, .asc) i pretvara ih. Za skeniranje svih datoteka, primjerak datoteke DirectoryWalker treba dostaviti metodi.

Trenutno Asciidoctor nudi dvije ugrađene implementacije spomenutog sučelja:

  • AsciiDocDirectoryWalker - pretvara sve datoteke date mape i njezine podmape. Zanemaruje sve datoteke koje počinju s “_”
  • GlobDirectoryWalker - pretvoriti sve datoteke date mape slijedeći glob izraz
Niz [] rezultat = asciidoctor.convertDirectory (novi AsciiDocDirectoryWalker ("src / asciidoc"), nova HashMap ()); 

Također, možemo pozvati metodu pretvorbe uz uvjet java.io.Čitač i java.io.Pisac sučelja.Čitač sučelje se koristi kao izvor, i Pisac sučelje se koristi za upisivanje pretvorenih podataka:

Čitač FileReader = novi FileReader (nova datoteka ("sample.adoc")); StringWriter Writer = novi StringWriter (); asciidoctor.convert (čitač, pisac, options (). asMap ()); StringBuffer htmlBuffer = Writer.getBuffer ();

5.2. Generacija PDF-a

Da bismo generirali PDF datoteku iz Asciidoc dokumenta, u opcijama moramo odrediti vrstu generirane datoteke. Ako malo pažljivije pogledate prethodne primjere, primijetit ćete da je drugi parametar bilo koje metode pretvorbe a Karta - koji predstavlja objekt mogućnosti.

Opciju in_place postavit ćemo na true, tako da se naša datoteka automatski generira i sprema u datotečni sustav:

Opcije karte = options () .inPlace (true) .backend ("pdf") .asMap (); String outfile = asciidoctor.convertFile (nova datoteka ("baeldung.adoc"), opcije);

6. Dodatak Maven

U prethodnom smo odjeljku pokazali kako PDF datoteku možemo generirati izravno vlastitom implementacijom u Javi. U ovom ćemo odjeljku pokazati kako generirati PDF datoteku tijekom izrade Mavena. Simiar dodaci postoje za Gradle i Ant.

Da biste omogućili generiranje PDF-a tijekom izrade, morate dodati ovu ovisnost u svoj pom.xml:

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

Najnoviju verziju ovisnosti o dodatku Maven možete pronaći ovdje.

6.1. Upotreba

Da biste koristili dodatak u izradi, morate ga definirati u pom.xml:

   output-html generiraj-resurse process-asciidoc 

Budući da dodatak ne radi u određenoj fazi, morate postaviti fazu u kojoj ga želite pokrenuti.

Kao i kod dodatka Asciidoctorj, i ovdje možemo koristiti razne mogućnosti za generiranje PDF-a.

Kratko ćemo pogledati osnovne opcije dok druge mogućnosti možete pronaći u dokumentaciji:

  • izvorDirektorij - mjesto direktorija u kojem imate Asciidoc dokumente
  • outputDirectory - mjesto direktorija u koji želite pohraniti generirane PDF datoteke
  • pozadina - vrsta rezultata iz Asciidoctora. Za generiranje PDF-a postavljen za pdf

Ovo je primjer kako definirati osnovne opcije u dodatku:

  src / main / doc target / docs pdf 

Nakon pokretanja gradnje, PDF datoteke se mogu naći u navedenom izlaznom direktoriju.

7. Zaključak

Iako je AsciiDoc vrlo jednostavan za korištenje i razumijevanje, vrlo je moćan alat za upravljanje dokumentacijom i ostalim dokumentima.

U ovom smo članku pokazali jednostavan način generiranja HTML i PDF datoteka iz AsciiDoc dokumenta.

Kôd se može pronaći preko na GitHub-u.


$config[zx-auto] not found$config[zx-overlay] not found