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.