AsciiDocからPDFを生成する手順をテンプレートにまとめる

最近は仕事や個人のメモの執筆環境をMarkdownからAsciiDocに切り替えています。 Markdownは何より手軽ですしこのブログも全部Markdownで書いているのですが、 AsciiDocの表現力の豊富さに慣れてしまうとMarkdownには戻ることはできません。 Asciidoctorを使えばHTMLも作れますし、 Asciidoctor PDFを使えばPDF生成もできちゃいます。

今回はAsciiDocの文章からPDFを生成する手順をテンプレート化したよという話。毎回忘れてGoogleしてしまうので、一式まとめたモノを作ってしまおうということです。

日本語が豆腐になる問題

Asciidoctor PDFはAsciiDoc文章からPDF生成するためのRuby製のライブラリです。スタイルを特に指定せずともそれなりに綺麗なPDFが出力されます。

ただ難点として、日本語の文章をAsciidoctor PDFにそのまま入力すると日本語が全部豆腐になります。これは既知の問題で回避策もIssue内に明示されています。

github.com

また、Qiitaにも多くの記事が書かれています。

qiita.com qiita.com

毎回やることは自動化しようぜ

上記の通り日本語豆腐問題はググればたくさんの解決策が出てきますが、毎回同じことをやるので自動化しちゃった方が後が楽になります。

実際に手順を自動化して出来上がったテンプレートのリポジトリは↓のようになりました。 github.com

あとはリポジトリをCloneしたりソースコードリポジトリにGitのサブモジュールとして組み込めば、簡単にPDFドキュメントを生成できます。

テンプレートのリポジトリでは何をやっているのか？

やっているのは以下3点だけです。

必要なライブラリ(Asciidoctor PDFなど)をGemfileにまとめる。
PDF生成コマンド一式をシェルスクリプトにまとめる。
ライブラリのインストールやシェル実行をMakefileに記述して実行する。

Makefileを一部抜粋すると、以下のように書いています。

.DEFAULT_GOAL := help

setup: ## 依存ライブラリをインストールする。
       @bundle config set path 'vendor'
       @bundle install
       @echo ">> Installed all dependencies"

pdf: ## PDFを生成する。
       @./scripts/build-pdf.sh

help: ## ヘルプを出力する。
       @grep -E '^[/a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | perl -pe 's%^([/a-zA-Z_-]+):.*?(##)%$$1 $$2%' | awk -F " *?## *?" '{printf "\033[36m%-15s\033[0m %-50s %s\n", $$1, $$2, $$3}'