«Введение в Asciidoctor в Java» - Spring на русском

«1. Введение

В этой статье мы кратко расскажем, как использовать Asciidoctor с Java. Мы покажем, как создать HTML5 или PDF из документа AsciiDoc.

2. Что такое AsciiDoc?

AsciiDoc — это формат текстового документа. Его можно использовать для написания документации, книг, веб-страниц, справочных страниц и многого другого.

Поскольку документы AsciiDoc легко настраиваются, их можно конвертировать во многие другие форматы, такие как HTML, PDF, справочные страницы, EPUB и другие.

Поскольку синтаксис AsciiDoc довольно простой, он стал очень популярным благодаря большой поддержке в различных плагинах для браузеров, плагинах для языков программирования и других инструментах.

Чтобы узнать больше об этом инструменте, мы предлагаем прочитать официальную документацию, где вы можете найти множество полезных ресурсов для изучения правильного синтаксиса и методов экспорта вашего документа AsciiDoc в другие форматы.

3. Что такое Asciidoctor?

Asciidoctor — это текстовый процессор для преобразования документов AsciiDoc в HTML, PDF и другие форматы. Он написан на Ruby и упакован как RubyGem.

Как упоминалось выше, AsciiDoc — очень популярный формат для написания документации, поэтому вы можете легко найти Asciidoctor в качестве стандартного пакета во многих дистрибутивах GNU Linux, таких как Ubuntu, Debian, Fedora и Arch.

Поскольку мы хотим использовать Asciidoctor на JVM, мы поговорим об AsciidoctorJ — это Asciidoctor с Java.

4. Зависимости

Чтобы включить пакет AsciidoctorJ в наше приложение, необходима следующая запись pom.xml:

<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj</artifactId>
    <version>1.5.5</version>
</dependency>
<dependency>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctorj-pdf</artifactId>
    <version>1.5.0-alpha.15</version>
</dependency>

Последние версии библиотек можно найти здесь и здесь.

5. AsciidoctorJ API

Точкой входа для AsciidoctorJ является интерфейс AsciidoctorJ Java.

Это следующие методы:

convert — анализирует документ AsciiDoc из строки или потока и преобразует его в предоставленный тип формата convertFile — анализирует документ AsciiDoc из предоставленного объекта File и преобразует его в предоставленный тип формата. convertFiles — то же, что и предыдущий, но метод принимает несколько объектов File convertDirectory — анализирует все документы AsciiDoc в указанной папке и преобразует их в указанный тип формата

5.1. Использование API в коде

Чтобы создать экземпляр Asciidoctor, вам нужно получить экземпляр из предоставленного фабричного метода:

import static org.asciidoctor.Asciidoctor.Factory.create;
import org.asciidoctor.Asciidoctor;
..
//some code
..
Asciidoctor asciidoctor = create();

С полученным экземпляром мы можем очень легко преобразовать документ AsciiDoc:

String output = asciidoctor
  .convert("Hello _Baeldung_!", new HashMap<String, Object>());

Если мы хотим преобразовать текстовый документ из файловой системы, мы будем использовать метод convertFile:

String output = asciidoctor
  .convertFile(new File("baeldung.adoc"), new HashMap<String, Object>());

Для преобразования нескольких файлов метод convertFiles принимает объект List в качестве первого параметра и возвращает массивы объектов String. Более интересно, как преобразовать весь каталог с помощью AsciidoctorJ.

Как упоминалось выше, для преобразования всего каталога — мы должны вызвать метод convertDirectory. Это сканирует предоставленный путь и ищет все файлы с расширениями AsciiDoc (.adoc, .ad, .asciidoc, .asc) и преобразует их. Для сканирования всех файлов методу необходимо предоставить экземпляр DirectoryWalker.

В настоящее время Asciidoctor предоставляет две встроенные реализации указанного интерфейса:

AsciiDocDirectoryWalker — конвертирует все файлы данной папки и ее подпапок. Игнорирует все файлы, начинающиеся с «_» GlobDirectoryWalker — конвертирует все файлы данной папки в соответствии с выражением glob

String[] result = asciidoctor.convertDirectory(
  new AsciiDocDirectoryWalker("src/asciidoc"),
  new HashMap<String, Object>());

Также мы можем вызвать метод convert с предоставленными интерфейсами java.io.Reader и java.io.Writer . В качестве источника используется интерфейс Reader, а для записи преобразованных данных используется интерфейс Writer:

FileReader reader = new FileReader(new File("sample.adoc"));
StringWriter writer = new StringWriter();
 
asciidoctor.convert(reader, writer, options().asMap());
 
StringBuffer htmlBuffer = writer.getBuffer();

5.2. Генерация PDF

Чтобы сгенерировать PDF-файл из документа Asciidoc, нам нужно указать тип сгенерированного файла в опциях. Если вы внимательно посмотрите на предыдущие примеры, то заметите, что вторым параметром любого метода convert является Map, который представляет объект параметров.

Мы установим для параметра in_place значение true, чтобы наш файл автоматически генерировался и сохранялся в файловой системе:

Map<String, Object> options = options()
  .inPlace(true)
  .backend("pdf")
  .asMap();

String outfile = asciidoctor.convertFile(new File("baeldung.adoc"), options);

6. Плагин Maven

«В предыдущем разделе мы показали, как мы можем создать PDF-файл напрямую с помощью вашей собственной реализации на Java. В этом разделе мы покажем, как создать файл PDF во время сборки Maven. Аналогичные плагины существуют для Gradle и Ant.

Чтобы включить генерацию PDF во время сборки, вам нужно добавить эту зависимость в ваш pom.xml:

<plugin>
    <groupId>org.asciidoctor</groupId>
    <artifactId>asciidoctor-maven-plugin</artifactId>
    <version>1.5.5</version>
    <dependencies>
        <dependency>
            <groupId>org.asciidoctor</groupId>
            <artifactId>asciidoctorj-pdf</artifactId>
            <version>1.5.0-alpha.15</version>
        </dependency>
    </dependencies>
</plugin>

Последнюю версию зависимости плагина Maven можно найти здесь.

6.1. Использование

Чтобы использовать плагин в сборке, вы должны определить его в pom.xml:

<plugin>
    <executions>
        <execution>
            <id>output-html</id> 
            <phase>generate-resources</phase> 
            <goals>
                <goal>process-asciidoc</goal> 
            </goals>
        </execution>
    </executions>
</plugin>

Поскольку плагин не запускается на какой-либо конкретной фазе, вы должны установить фазу там, где вы хотите чтобы начать это.

Как и в случае с плагином Asciidoctorj, здесь мы также можем использовать различные опции для генерации PDF.

Давайте кратко рассмотрим основные параметры, в то время как вы можете найти другие параметры в документации:

sourceDirectory — расположение каталога, в котором у вас есть документы Asciidoc. для хранения сгенерированных файлов PDF — тип вывода Asciidoctor. Для набора PDF-генерации для pdf

Это пример того, как определить основные параметры в плагине:

<plugin>
    <configuration>
        <sourceDirectory>src/main/doc</sourceDirectory>
        <outputDirectory>target/docs</outputDirectory>
        <backend>pdf</backend>
    </configuration>
</plugin>

После запуска сборки PDF-файлы можно найти в указанном выходном каталоге.

7. Заключение

Несмотря на то, что AsciiDoc очень прост в использовании и понимании, это очень мощный инструмент для управления документацией и другими документами.

В этой статье мы продемонстрировали простой способ создания файлов HTML и PDF из документа AsciiDoc.

Код можно найти на GitHub.

«Введение в Asciidoctor в Java»