JavaでのAsciidoctorの概要
1. 前書き
この記事では、JavaでAsciidoctorを使用する方法について簡単に紹介します。 AsciiDocドキュメントからHTML5またはPDFを生成する方法を示します。
2. AsciiDocとは何ですか？
AsciiDocはテキストドキュメント形式です。 writing documentation, books, web pages, man pages and many other.に使用できます
AsciiDocドキュメントは非常に構成可能であるため、HTML、PDF、マニュアルページ、EPUBなどの他の多くの形式に変換できます。
AsciiDoc構文は非常に基本的なものであるため、さまざまなブラウザプラグイン、プログラミング言語のプラグイン、およびその他のツールでの大規模なサポートで非常に人気が高まっています。
ツールの詳細については、official documentationをお読みになることをお勧めします。ここでは、AsciiDocドキュメントを他の形式にエクスポートするための適切な構文と方法を学習するための多くの役立つリソースを見つけることができます。
3. Asciidoctorとは何ですか？
Asciidoctorは、HTML、PDF、およびその他の形式のtext processor for converting AsciiDoc documentsです。 Rubyで書かれ、RubyGemとしてパッケージ化されています。
前述のように、AsciiDocはドキュメントを記述するための非常に一般的な形式であるため、Ubuntu、Debian、Fedora、Archなどの多くのGNU LinuxディストリビューションでAsciidoctorを標準パッケージとして簡単に見つけることができます。
JVMでAsciidoctorを使用したいので、JavaでのAsciidoctorであるAsciidoctorJについて説明します。
4. 依存関係
5. AsciidoctorJ API
AsciidoctorJのエントリポイントは、AsciidoctorJavaインターフェイスです。
それらのメソッドは次のとおりです。
-
convert – AsciiDocドキュメントをStringまたはStreamから解析し、提供された形式タイプに変換します
-
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 _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のインスタンスをメソッドに提供する必要があります。
現在、Ascidoctorは上記のインターフェイスの2つの組み込み実装を提供しています。
-
AsciiDocDirectoryWalker –指定されたフォルダーとそのサブフォルダーのすべてのファイルを変換します。 「_」で始まるすべてのファイルを無視します
-
GlobDirectoryWalker –glob式に従って指定されたフォルダーのすべてのファイルを変換します
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.前の例をもう少し注意深く見ると、変換メソッドの2番目のパラメーターがMapであることがわかります。これはオプションオブジェクトを表します。
in_placeオプションをtrueに設定して、ファイルが自動的に生成され、ファイルシステムに保存されるようにします。
Map options = options()
.inPlace(true)
.backend("pdf")
.asMap();
String outfile = asciidoctor.convertFile(new File("example.adoc"), options); 6. Mavenプラグイン
前のセクションでは、Javaで独自の実装を使用してPDFファイルを直接生成する方法を示しました。 このセクションでは、Mavenビルド中にPDFファイルを生成する方法を示します。 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は非常に使いやすく理解しやすいものですが、ドキュメントやその他のドキュメントを管理するための非常に強力なツールです。
この記事では、AsciiDoc文書からHTMLおよびPDFファイルを生成する簡単な方法を示しました。
コードはover on GitHubにあります。