Перейти к основному содержимому

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

· 5 мин. чтения

1. Введение​

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

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

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

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

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

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

3. Что такое Аскиддоктор?​

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. API AsciidoctorJ​

Точкой входа для AsciidoctorJ является интерфейс Asciidoctor 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 _ForEach_!", new HashMap<String, Object>());

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

String output = asciidoctor
  .convertFile(new File("foreach.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("foreach.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.
  • outputDirectory — расположение каталога, в котором вы хотите хранить сгенерированные PDF-файлы.
  • backend — тип вывода 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 .