1. Pengenalan
Dalam artikel ini, kami akan membuat pengenalan ringkas mengenai cara menggunakan Asciidoctor dengan Java. Kami akan menunjukkan cara menghasilkan HTML5 atau PDF dari dokumen AsciiDoc.
2. Apakah AsciiDoc?
AsciiDoc adalah format dokumen teks. Ia boleh digunakan untuk menulis dokumentasi, buku, halaman web, halaman manual dan banyak lagi.
Oleh kerana ia sangat boleh dikonfigurasi, dokumen AsciiDoc dapat ditukar menjadi banyak format lain seperti HTML, PDF, halaman manual, EPUB, dan lain-lain.
Kerana sintaks AsciiDoc cukup mendasar, ia menjadi sangat popular dengan sokongan yang besar dalam pelbagai plugin penyemak imbas, plugin untuk bahasa pengaturcaraan dan alat lain.
Untuk mengetahui lebih lanjut mengenai alat ini, kami mencadangkan membaca dokumentasi rasmi di mana anda boleh mendapatkan banyak sumber berguna untuk mempelajari sintaks dan kaedah yang betul untuk mengeksport dokumen AsciiDoc anda ke format lain.
3. Apa itu Asciidoctor?
Asciidoctor adalah pemproses teks untuk menukar dokumen AsciiDoc menjadi HTML, PDF dan format lain. Ia ditulis dalam Ruby dan dibungkus sebagai RubyGem.
Seperti yang disebutkan di atas, AsciiDoc adalah format yang sangat popular untuk menulis dokumentasi, jadi anda dapat dengan mudah menemukan Asciidoctor sebagai pakej standard dalam banyak pengedaran Linux GNU seperti Ubuntu, Debian, Fedora, dan Arch.
Oleh kerana kami ingin menggunakan Asciidoctor di JVM, kami akan membincangkan mengenai AsciidoctorJ - yang merupakan Asciidoctor dengan Java.
4. Kebergantungan
Untuk memasukkan pakej AsciidoctorJ dalam aplikasi kami, masukan pom.xml berikut diperlukan:
org.asciidoctor asciidoctorj 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 Versi perpustakaan terkini boleh didapati di sini dan di sini.
5. API AsciidoctorJ
Titik masuk untuk AsciidoctorJ adalah antara muka Asciidoctor Java.
Kaedah tersebut adalah:
- convert - menguraikan dokumen AsciiDoc dari String atau Stream dan menukarnya ke jenis format yang disediakan
- convertFile - menguraikan dokumen AsciiDoc dari objek Fail yang disediakan dan menukarnya ke jenis format yang disediakan
- convertFiles - sama seperti sebelumnya, tetapi kaedah menerima banyak objek Fail
- convertDirectory - menguraikan semua dokumen AsciiDoc dalam folder yang disediakan dan menukarnya ke jenis format yang disediakan
5.1. Penggunaan API dalam Kod
Untuk membuat instance Asciidoctor , anda perlu mengambil instance dari kaedah kilang yang disediakan:
import static org.asciidoctor.Asciidoctor.Factory.create; import org.asciidoctor.Asciidoctor; .. //some code .. Asciidoctor asciidoctor = create(); Dengan contoh yang diambil, kita dapat menukar dokumen AsciiDoc dengan sangat mudah:
String output = asciidoctor .convert("Hello _Baeldung_!", new HashMap());Sekiranya kita ingin menukar dokumen teks dari sistem fail, kita akan menggunakan kaedah convertFile :
String output = asciidoctor .convertFile(new File("baeldung.adoc"), new HashMap()); Untuk menukar beberapa fail, kaedah convertFiles menerima objek List sebagai parameter pertama dan mengembalikan array objek String .
Lebih menarik adalah bagaimana menukar keseluruhan direktori dengan AsciidoctorJ.
Seperti yang disebutkan di atas, untuk mengubah keseluruhan direktori - kita harus memanggil kaedah convertDirectory . Ini mengimbas jalan yang disediakan dan mencari semua fail dengan sambungan AsciiDoc (.adoc, .ad, .asciidoc, .asc) dan menukarnya. Untuk mengimbas semua fail, contoh DirectoryWalker harus diberikan kepada kaedah tersebut.
Pada masa ini, Asciidoctor menyediakan dua implementasi antara muka yang disebutkan:
- AsciiDocDirectoryWalker - menukar semua fail folder yang diberikan dan subfoldernya. Mengabaikan semua fail bermula dengan “_”
- GlobDirectoryWalker - menukar semua fail folder yang diberikan mengikuti ungkapan glob
String[] result = asciidoctor.convertDirectory( new AsciiDocDirectoryWalker("src/asciidoc"), new HashMap()); Juga, kita boleh memanggil kaedah menukar dengan antaramuka java.io.Reader dan java.io.Writer yang disediakan . Antaramuka pembaca digunakan sebagai sumber, dan antara muka Penulis digunakan untuk menulis data yang ditukar:
FileReader reader = new FileReader(new File("sample.adoc")); StringWriter writer = new StringWriter(); asciidoctor.convert(reader, writer, options().asMap()); StringBuffer htmlBuffer = writer.getBuffer();5.2. Penjanaan PDF
Untuk menghasilkan fail PDF dari dokumen Asciidoc, kita perlu menentukan jenis fail yang dihasilkan dalam pilihan. Sekiranya anda melihat dengan teliti contoh sebelumnya, anda akan melihat bahawa parameter kedua kaedah menukar adalah Peta - yang mewakili objek pilihan.
Kami akan menetapkan pilihan in_place menjadi benar sehingga fail kami dihasilkan secara automatik dan disimpan ke sistem fail:
Map options = options() .inPlace(true) .backend("pdf") .asMap(); String outfile = asciidoctor.convertFile(new File("baeldung.adoc"), options);6. Plugin Maven
Pada bahagian sebelumnya, kami menunjukkan bagaimana kami dapat menghasilkan file PDF secara langsung dengan implementasi Anda sendiri di Java. Di bahagian ini, kami akan menunjukkan bagaimana anda menghasilkan fail PDF semasa pembuatan Maven. Plugin Simiar ada untuk Gradle dan Ant.
Untuk membolehkan penjanaan PDF semasa pembuatan, anda perlu menambahkan kebergantungan ini ke pom.xml anda :
org.asciidoctor asciidoctor-maven-plugin 1.5.5 org.asciidoctor asciidoctorj-pdf 1.5.0-alpha.15 Versi terbaru dari pergantungan plugin Maven boleh didapati di sini.
6.1. Penggunaan
Untuk menggunakan pemalam dalam binaan, anda harus menentukannya dalam pom.xml:
output-html generate-resources process-asciidoc Oleh kerana pemalam tidak berjalan dalam fasa tertentu, anda harus menetapkan fasa di mana anda ingin memulakannya.
Seperti plugin Asciidoctorj, kita juga boleh menggunakan pelbagai pilihan untuk penjanaan PDF di sini.
Mari kita lihat dengan cepat pilihan asas sementara anda dapat mencari pilihan lain dalam dokumentasi:
- sourceDirectory - lokasi direktori di mana anda mempunyai dokumen Asciidoc
- outputDirectory - lokasi direktori di mana anda ingin menyimpan fail PDF yang dihasilkan
- backend - jenis output dari Asciidoctor. Untuk set generasi PDF untuk pdf
Ini adalah contoh bagaimana menentukan pilihan asas dalam pemalam:
src/main/doc target/docs pdf Setelah menjalankan build, fail PDF dapat ditemukan di direktori output yang ditentukan.
7. Kesimpulannya
Walaupun AsciiDoc sangat mudah digunakan dan difahami, ia adalah alat yang sangat ampuh untuk menguruskan dokumentasi dan dokumen lain.
Dalam artikel ini, kami menunjukkan cara mudah untuk menghasilkan fail HTML dan PDF dari dokumen AsciiDoc.
Kodnya boleh didapati di GitHub.