TOC

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

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

1. Вступление

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

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

AsciiDoc - это формат текстового документа. Его можно использовать дляwriting documentation, books, web pages, man pages and many other.

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

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

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

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

Asciidoctor - этоtext processor for converting AsciiDoc documents в HTML, PDF и других форматах. Он написан на Ruby и упакован как RubyGem.

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

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

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

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


    org.asciidoctor
    asciidoctorj
    1.5.5


    org.asciidoctor
    asciidoctorj-pdf
    1.5.0-alpha.15

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

5. API AsciidoctorJ

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

Эти методы:

  • convert - анализирует документ AsciiDoc изString илиStream и преобразует его в предоставленный тип формата

  • 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 _example_!", new HashMap());

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

String output = asciidoctor
  .convertFile(new File("example.adoc"), new HashMap());

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

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

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

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

  • GlobDirectoryWalker - конвертировать все файлы данной папки, следуя глобальному выражению 

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

Кроме того, интерфейсwe can call convert method with provided java.io.Reader and java.io.Writer interfaces.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

To generate a PDF file from an Asciidoc document, we need to specify the type of the generated file in options. Если вы посмотрите немного внимательнее на предыдущие примеры, вы заметите, что вторым параметром любого метода преобразования являетсяMap, который представляет объект параметров.

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

Map options = options()
  .inPlace(true)
  .backend("pdf")
  .asMap();

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

6. Maven Plugin

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

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


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

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

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

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


    
        
            output-html
            generate-resources
            
                process-asciidoc

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

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

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

  • sourceDirectory - расположение каталога, в котором находятся документы Asciidoc

  • outputDirectory - расположение каталога, в котором вы хотите хранить сгенерированные файлы PDF

  • backend - тип вывода Asciidoctor. Для создания PDF-набора для PDF

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


    
        src/main/doc
        target/docs
        pdf

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

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

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

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

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

Related