GitHub Actionsで利用したいAsciidoctorの環境 | cloud.config Tech Blog

はじめに

前回までは2回にわたりAsciiDoc出力に利用した「Analog-inc/Asciidoctor-action」アクションの大まかな内容を解説しました。
今回はその内部で利用しているAsciidoctor実行環境について簡単に説明します。
今回の内容をお読みいただければ、まだHTMLしか出力していないAsciiDocについてPDFやePubなどの出力環境構築についても簡単に知ることができると思います。

前回までの記事について

これまでの記事はこちらにあります。　そちらも合わせてお読みいただけると嬉しいです。

Asciidoctorについて

Asciidoctorは、AsciiDoc形式のための包括的なツールで、AsciiDoc形式をHTML5、DocBook、PDFなどの形式に変換します。

Asciidoctorの歴史

Asciidoctorは2012年にGitHub開発者であるNick HengeveldがGitのウェブサイトに示されているgitのマニュアルページを生成するために作成したプロトタイプをベースに、同じくGitHub開発者であるRyan Waldronがプロジェクトを開始しました。
2013年にAsciidoctorがGitHubにおいて発表され、その後はオープンソースプロジェクトとしてGitHubでホストされています。

このため、GitHubではサイト上で.adocファイルのプレビューを行うことができ、READMEやWikiをAsciiDoc形式で記述することが可能です。

Asciidoctorが動く環境

AsciidoctorはRubyで実装されおり、インストールを簡略化するためにパッケージ化されてRubyGemとして配布されています。

また人気のあるLinuxディストリビューションやmacOS用のパッケージとしても配布されており、すべての主要なオペレーティングシステムで動作します。
Rubyで実行されるほかにAsciidoctorJを使用してJVM上で実行することや、Asciidoctor.jsを使用してブラウザを含むJavaScript環境で実行することもできます。

それぞれの詳しいインストール方法は以下のリンクにあります。

インストール方法

Github Actionsで利用した環境について

「Analog-inc/Asciidoctor-action」で利用しているAsciidoctorは上記のに紹介したリンクのインストール方法の内、Dockerを利用しています。
その理由として以下の点が挙げられます。

出力対象となる形式の多くに対応している

実は上記のに紹介したリンクのインストール方法のほどんどgem installもAPTもHTML出力にしか対応していません。
実際の運用ではHTMLと同時にPDFも出力したかったりする場合もあるかと思いますが、そのために「asciidoctor-pdf」など必要な物を選んでインストールする必要があります。
一方でDockerを利用した場合は多くの出力形式に対応しています。

ドキュメントの表現に必要な多くのオプションに対応している

Asciidoctorを利用するとコードハイライト、ダイアグラム生成、数式表記など多くの外部ライブラリを利用してドキュメントを表現することが可能です。
gem installやAPTを利用したインストールの場合は、それらの外部ライブラリを自分で選んでインストールする必要があります。
一方でDockerを利用した場合は多くの表現方法を利用可能です。

上記の様な対応を公式にまとめた環境の最新版を常に利用できる

gem installやAPTを利用し自分でインストールした環境を維持するには定期的な更新が必要になります。また、多くの人が使うGitHub上のリポジトリなどでは何が利用できて何が利用できないなど、環境ごとに異なる仕様があると現場に混乱を招きます。
Dockerを利用することでその様な混乱を避けることができます。

Dockerの可搬性や軽量・高速なメリットを活かせる

この部分の説明は次回以降の記事にて触れますが、Docerを利用する場合はリポジトリから対象となるイメージのダウンロードは必要になりますが、インストール作業は発生しません。
また、ダウンロードしたイメージで環境が固定されるわけでなく、それぞれの利用環境で必要な機能を個別に追加することも可能です。
これらの特徴により、すぐに使いたい機能をGitHub Actionsのホストランナー上で利用することができます。

まとめ

今回はAsciidoctorの概要とともに、なぜDockerでAsciidoctorを利用したいのかを簡単に解説しました。
次回は少し難しい話になりますが、「Analog-inc/Asciidoctor-action」で利用したDockerコンテナの技術について少し説明したいと思います。