JavaでのAsciidoctorの紹介

投稿日: 2019-10-18 2022-11-09
タグ: Programming

1. 序章

この記事では、JavaでAsciidoctorを使用する方法について簡単に紹介します。 AsciiDocドキュメントからHTML5またはPDFを生成する方法を示します。

2. AsciiDocとは何ですか？

AsciiDocはテキストドキュメント形式です。 ドキュメント、書籍、Webページ、マニュアルページ、その他多くの書き込みに使用できます。

AsciiDocドキュメントは非常に構成可能であるため、HTML、PDF、マニュアルページ、EPUBなどの他の多くの形式に変換できます。

AsciiDoc構文は非常に基本的なものであるため、さまざまなブラウザプラグイン、プログラミング言語用のプラグイン、およびその他のツールで大規模なサポートが行われるようになり、非常に人気があります。

このツールの詳細については、公式ドキュメントを読むことをお勧めします。ここでは、AsciiDocドキュメントを他の形式にエクスポートするための適切な構文と方法を学習するための多くの役立つリソースを見つけることができます。

3. Asciidoctorとは何ですか？

Asciidoctor は、AsciiDocドキュメントをHTML、PDF、およびその他の形式に変換するためのテキストプロセッサです。これはRubyで書かれ、RubyGemとしてパッケージ化されています。

前述のように、AsciiDocはドキュメントを作成するための非常に一般的な形式であるため、Ubuntu、Debian、Fedora、Archなどの多くのGNULinuxディストリビューションで標準パッケージとしてAsciidoctorを簡単に見つけることができます。

JVMでAsciidoctorを使用したいので、Javaを備えたAsciidoctorであるAsciidoctorJについて説明します。

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のエントリポイントは、 AsciidoctorJavaインターフェイスです。

それらの方法は次のとおりです。

convert – StringまたはStreamからAsciiDocドキュメントを解析し、提供されたフォーマットタイプに変換します
convertFile –提供された File オブジェクトからAsciiDocドキュメントを解析し、提供されたフォーマットタイプに変換します
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は、前述のインターフェースの2つの組み込み実装を提供しています。

AsciiDocDirectoryWalker –指定されたフォルダーとそのサブフォルダーのすべてのファイルを変換します。「_」で始まるすべてのファイルを無視します
GlobDirectoryWalker –glob式に従って指定されたフォルダーのすべてのファイルを変換します

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

また、提供されたjava.io.Readerおよびjava.io.Writerインターフェースを使用してconvertメソッドを呼び出すことができます。 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生成

AsciidocドキュメントからPDFファイルを生成するには、オプションで生成されたファイルのタイプを指定する必要があります。前の例をもう少し注意深く見ると、 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プラグイン

前のセクションでは、Javaで独自の実装を使用してPDFファイルを直接生成する方法を示しました。このセクションでは、Mavenビルド中にPDFファイルを生成する方法を示します。 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は非常に使いやすく理解しやすいものですが、ドキュメントやその他のドキュメントを管理するための非常に強力なツールです。

この記事では、AsciiDocドキュメントからHTMLおよびPDFファイルを生成する簡単な方法を示しました。

コードはGitHubのにあります。

getdocs

13036