追記4（2022/10/8）
asciidoctor-pdf 2.0あたりでテーマファイルを指定する引数が変更されています。
この記事で紹介しているテーマファイルの指定方法ではうまくかなくなっています。
対応方法については、このことを気づかせてくれた記事「 asciidoctor-pdfでのテーマファイルの指定」を参照することをお勧めします。また、テーマの各パラメータにも変更があります。そちらは、asciidoctor-pdfのテーマファイルのリファレンスを見れば解決できるでしょう。
追記3（2021/07/12）
この記事の説明は、asciidoctor-pdfの1.5.x までに対応したものです。
それ以外の体裁に関するテーマの設定は、まだ使えると思います（全部は確認していませんのであしからず）。asciidoctor-pdfの1.6以降では、 asciidoctor-pdf-cjk を使うのをやめて、代わりに asciidcotor-pdf の-a scripts=cjk オプションを追加します。
asciidoctor-pdfの1.5まで：
（asciidoctor-pdf-cjkをgemでインストールした上で）asciidoctor-pdf -r asciidoctor-pdf-cjk その他の引数…asciidoctor-pdfの1.6以降
（asciidoctor-pdf-cjkをgemはインストールせずに）asciidoctor-pdf -a scripts=cjk その他の引数…詳しくは、 [asciidoctor-pdfで日本語を含むPDFの出力を行う] (https://qiita.com/mitsu48/items/34875bbc8ba00760fe27#_reference-e1f72ce5e5f3d9cef664) を参考にするとよいでしょう。
追記2
技術書典8で頒布予定だったレシピ集Vol. 2「Raspberry Pi もっと食べたいレシピ集」をオンライン販売しています（ごめんなさい。その後オンライン販売は終了しました）。この本も、著者たちが asciidoctor を使って執筆し、 asciidoctor-pdf を使ってPDF出力したものを入稿しました。章題の体裁、ノンブルの挿入、アイコン付きの対話形式など、この記事では扱えていない体裁のアレンジにもチャレンジしています（それ記事にしろよ、自分！）。
追記1
技術書典6（い14）で 「Raspberry Pi 今すぐ食べたいレシピ集」も電子版は引き続き販売しています。この本は、著者たちが asciidoctor を使って執筆し、 asciidoctor-pdf を使ってPDF出力したものを入稿しました。
asciidoctorは快適なのだがPDFが…
asciidoctorを使うと文書作成が快適です。出力されるhtmlもまずまずの出来栄えだと思います。そして、asciidoctor-pdf を使うとPDFプリンタなどを使わなくても、直接PDFが得られます。素晴らしい。ところが、初期設定のままでは出来栄えがあまりパッとしないのです。もうチョットなんとかならないかと思っていました。
この記事では、設定を調整して見栄えのよいPDFを作成した手順を紹介します。
最終型は、こんな感じです。
前提
すでに諸兄が asciidoctor の素晴らしさについては言及しているので、asciidoctorそのものについては説明しません。次のリンクを参考にしてください。
この記事では、みなさんがある程度 asciidoctor は使える状況にあるとします。
また、rakeコマンドなどを使って楽に作成する方法についても、この記事では触れません。他の方の記事などを参考に各自でお願いします。
設定のヒント
この記事の設定のほとんどは、Asciidoctor PDF Theming Guide を参考にしています。
このページを読んで設定すれば、みなさんもお好みのページに近づけるのではないかと思います。
わたしの場合、いちばんのポイントは本文と章節の見出しに使う日本語フォントを変えることでした。
プログラムのインストール
asciidoctor-pdf の Prerequisites を確認して、必要なプログラムをインストールします。
asciidoctor-pdf は、rubyのバージョンについて 2.3.0 以上を推奨しています。
わたしは、MacOS上のRuby 2.3.x と下記の環境を使いました。
- asciidoctor (1.5.6.1)
- asciidoctor-pdf (1.5.0.alpha.16)
- クロスリファレンスの表記に図表番号を反映するには、このバージョン以降を使うこと
- まだ新しいパッケージのため、
gem install asciidoctor-pdf --preでインストールしました
- asciidoctor-pdf-cjk (0.1.3)
- 日本語を使った文章向けの設定が入っています
- rouge (2.1.1)
- ソースコードの整形用に使いました
- 開始行番号が指定できるので、これにしました
asciidoctor-pdf は、インストール時に prawn がインストールしてあるか調べ、なければ prawn もインストールします。すでに別途使っている場合には、バージョンを確認しておきましょう。
自分の環境では下記のバージョンでした。
- prawn (2.2.2)
- prawn-svg (0.24.0)
- prawn-templates (0.0.4)
元になる文書を作成する
設定を調整する前に、asciidoctor でいう book の構造を持つ単純なサンプル文書を作成し、この文書からPDFが作成できることを確認しましょう。その後、設定を調整しながらこの文書の変化を見ようと思います。
ここでは、自分のホームディレクトリ（自分の場合 /Users/kuboaki ）の Documents フォルダにテスト用フォルダ（ adoc-test ）を作成し、そこに文書や関連ファイルを作成しました。
$ cd ~/Documents/adoc-test
$ vim exapmle01.adoc
asciidoctor形式の文書を作る時（includeする文書も含め）、utf-8を使わないと変換時にエラーになります。
PDFを作ってみる
asciidoctor-pdf コマンドを使ってPDFを作成してます。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk exapmle.adoc
日本語含む文書の場合、最低限 -r asciidoctor-pdf-cjk というオプションを指定します。このオプションがない状態で作成したPDFは、半角と全角が混じる段落があると次のような感じになり、あまりいただけないです。
この記事を読んでいる方はご存知でしょうが、次のようにしてhtmlファイルが作れます。
$ asciidoctor -b html5 exapmle01.adoc
同じ文書ファイルから、HTML、PDFが作成できるのですが、比べてみると見かけがだいぶ異なっていることがわかると思います。
asciidoctor-pdf用テーマファイルを作る
PDFが作成できることが確認できたので、少しずつスタイルを調整します。
まず、asciidoctor-pdfの配布ファイルの data/themes から default-theme.yml を複製して mystyle-theme.yml を作ります。
$ cp （asciidoctor-pdfのインストールディレクトリ)/data/theme/default-theme.yml mystyle-theme.yml
このテーマファイルを使ってPDFを作成できることを確認します。
テーマファイルを指定するときは、次のように pdf-style
オプションを使います。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml example01.adoc -o example01_d.pdf
上記の指定方法は、asciidoctor-pdf 2.0以降では使えません。追記3や下記の記述を参考にしてください。
asciidoctor-pdf -a scripts=cjk -a pdf-theme=mystyle-theme.yml example01.adoc -o example01_d.pdfテーマファイルの置き場所の指定方オプションも2.0以降変わりました。詳細は、
テーマファイルの設定項目のDeprecatedになった項目 を参照してください。
最後の -o オプションは出力するPDFファイルのファイル名を指定するためのものです。省略すると、入力ファイル名の拡張子を.pdfにしたものが作られます。
テーマファイルが別のディレクトリにあると次のようなエラーになります。
$ mkdir theme
$ mv mystyle-theme.yml theme
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml example02.adoc
No such file or directory @ rb_sysopen - default-theme.yml
Use --trace for backtrace
この場合、 pdf-stylesdir オプションを使ってディレクトリを指定します。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-stylesdir=theme -a pdf-style=mystyle-theme.yml example02.adoc
できたPDFは、最初のPDFと変わりがないと思います。ですが、テーマファイルを使って作成したので、ここからは少しずつスタイルを調整していけます。
別の日本語フォントを入手する
asciidoctor-pdf自身の配布ファイルの中には Noto Serif というゴシック系の日本語フォントが含まれていて、example01.pdfではこのフォントが使われています。これを、本文に明朝系を使い、見出しに角ゴシック系のフォントを使うように変更してみようと思います。
現在のところ、asciidoctor-pdfで使えるのTrueTypeフォントだけです。本文用はプロポーショナルな明朝体を、見出しには太字の設定が豊富でプロポーショナルなゴシック体を選んでおくとよいと思い、次のフォントを使うことにしました。
モノスペースのフォントは、ソースコードを扱うことを考えて、プログラマが使うような等幅フォントを選んでみました。
- 明朝体：AozoraMincho （あおぞら明朝）
- ゴシック体：GenShinGothic-P（源真ゴシック-P）
- モノスペース：RictyDiminished
書体として normal、 bold、 italic、bold_italic が選べるとよいのですが、わたしにはそのような書体を持つ日本語TrueTypeフォントはみつけられませんでした。
わたしはこれらのフォントをシステムにインストールして使っていますが、PDFの作成に使うだけならば、フォントをシステムにインストールしなくてもかまいません。
ここでは、 fonts ディレクトリを作成して、ここにフォントを置いて使ってみます。
$ ls fonts
AozoraMincho-bold.ttf AozoraMinchoRegular.ttf GenShinGothic-P-Normal.ttf
AozoraMincho-thin.ttf GenShinGothic-P-Bold.ttf GenShinGothic-P-Regular.ttf
AozoraMinchoBlack.ttf GenShinGothic-P-ExtraLight.ttf RictyDiminished-Bold.ttf
AozoraMinchoHeavy.ttf GenShinGothic-P-Heavy.ttf RictyDiminished-BoldOblique.ttf
AozoraMinchoLight.ttf GenShinGothic-P-Light.ttf RictyDiminished-Oblique.ttf
AozoraMinchoMedium.ttf GenShinGothic-P-Medium.ttf RictyDiminished-Regular.ttf
フォント設定を編集する
テーマファイル中のフォントの設定を編集します。
追記：
Asciidoctor-pdf 2.0 では、フォントの扱いもすこし変わっています。また、基本的なCJK用のフォントも同梱されるようになりました。次のように書いておけば、defaultの設定に対する差分を書けば済むようになりました。
mystyle-theme.ymlextends: default font: catalog: AozoraMincho: （略）
catalog の下に設定用のフォントファミリ名を作成し、その下にスタイルごとに使用するフォントファイル名を指定します。基本的には default.yml の記述を活かし、そこに追加した日本語フォントの設定を追加します。
font:
catalog:
AozoraMincho:
normal: AozoraMinchoRegular.ttf
italic: AozoraMinchoMedium.ttf
bold: AozoraMinchoHeavy.ttf
bold_italic: AozoraMinchoBlack.ttf
GenShinGothic-P:
normal: GenShinGothic-P-Normal.ttf
italic: GenShinGothic-P-Regular.ttf
bold: GenShinGothic-P-Medium.ttf
bold_italic: GenShinGothic-P-Bold.ttf
RictyDiminished:
normal: RictyDiminished-Regular.ttf
italic: RictyDiminished-Oblique.ttf
bold: RictyDiminished-Bold.ttf
bold_italic: RictyDiminished-BoldOblique.ttf
M+ 1mn:
normal: mplus1mn-regular-ascii-conums.ttf
bold: mplus1mn-bold-ascii.ttf
italic: mplus1mn-italic-ascii.ttf
bold_italic: mplus1mn-bold_italic-ascii.ttf
M+ 1p Fallback:
normal: mplus1p-regular-fallback.ttf
bold: mplus1p-regular-fallback.ttf
italic: mplus1p-regular-fallback.ttf
bold_italic: mplus1p-regular-fallback.ttf
fallbacks:
- M+ 1p Fallback
（略）
当初は、italicや斜体がないフォントでは normal と同じ書体を選べばよいかと考えました。しかし、ここでいうitalicは、強調したい場合のスタイルの指定です。これを normal と同じスタイルにしてしまっては強調になりません。そこで（見てくれは多少犠牲にして）、italicや bold_italic には、太さの異なる同じ書体を設定してみました。
その後に続く M+ 1mn は、ソースコードのコメントに使う callout の丸数字などのために用意してあるフォントの指定です。
fallbacks は、選択中のフォントに出力対象の文字が見つからないとき、代用フォントとして使うフォントの設定です。上の設定では、 M+ 1p Fallback に指定のフォント、つまり mplus1p-regular-fallback.ttf が使われます。
M+ 1mn と M+ 1p Fallback に指定のフォントも、さきほど入手したフォントと同じ fonts ディレクトリにコピー（またはインストール）しておきます。これを忘れると、PDF作成時にフォントが見つからないというエラーになります。
$ cp （asciidoctor-pdfのインストールディレクトリ)/data/fonts/mplus*.ttf fonts
次に、再び mystyle-theme.yml を編集します。本文のフォントに Noto Serif が指定してあるので、これを今回入手した AozoraMincho に置き換えます。
ついでに、本文を左寄せにし、フォントサイズを10ポイント、行送りを1.5行に変更しました。
（略）
base:
align: left
font_color: 333333
font_family: AozoraMincho # Noto Serif
font_size: 10
line_height_length: 15
line_height: $base_line_height_length / $base_font_size
font_size_large: round($base_font_size * 1.25)
font_size_small: round($base_font_size * 0.85)
font_size_min: $base_font_size * 0.75
font_style: normal
border_color: eeeeee
border_radius: 4
border_width: 0.5
（略）
フォントの変更を確認する
フォント設定の変更の効果があるかどうか確認します。
example01.adocを修正してexample02.adocを作ります。
normal、 italic、 bold、 bold_italic の違いがわかるよう、次のように修正してみました。
（略）
== はじめに
normal: ここに「はじめに」にあたる文章を書く。
// italicによる強調は「_」で囲む
italic: _ここに「はじめに」にあたる文章を書く。_
// boldによる強調は「*」で囲む
bold: *ここに「はじめに」にあたる文章を書く。*
// bold_italicによる強調は「*_」で囲む
bold_italic: *_ここに「はじめに」にあたる文章を書く。_*
（略）
asciidoctor-pdf コマンドを使って再びPDFを作成します。今回は、 pdf-fontsdir を使ってフォントを置いたディレクトリを指定します。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml -a pdf-stylesdir=theme -a pdf-fontsdir=fonts example02.adoc
このディレクトリの指定に ~ を使いたくなりますが、どうもホームディレクトリ名には展開されないようです。
作成したPDFに使われているフォントが「あおぞら明朝」に変わりました。「はじめに」の本文は、原稿の中でitalicによって強調している箇所が「あおぞら明朝」の太字を使って代用できているのがわかります。
また、「最初の章」の本文をみると、行間が拡がって読みやすくなっています。
章節の見出しを調整する
章や節の見出しに使うフォントを角ゴシック系のフォントに変更し、フォントサイズ、行送り、色などを調整します。
フォントサイズは、個別に指定せず、本文のフォントサイズ（$base_font_size ）を元に計算しています。
（略）
heading:
align: left
font_color: 2D466B
font_family: GenShinGothic-P
font_style: bold
# h1 is used for part titles (book doctype only)
h1_font_size: floor($base_font_size * 2.4)
h2_font_size: floor($base_font_size * 2.4)
h3_font_size: round($base_font_size * 1.7)
h4_font_size: round($base_font_size * 1.4)
h5_font_size: $base_font_size
h6_font_size: $base_font_size_small
line_height: 1.4
margin_top: $vertical_rhythm * 0.9
margin_bottom: $vertical_rhythm * 0.9
（略）
見出しの変更を確認する
見出しを変更した効果があることを確認します。
example02.adocを修正してexample03.adocを作ります。
ついでに、章、節、目次などが日本語になるよう、文書の冒頭でこれらのラベルを設定します。
:encoding: utf-8
:lang: ja
:author: 著者名
:doctitle: サンプル文書のタイトル: 文書のサブタイトル
:doctype: book
:toc: left
:chapter-label:
:figure-caption: 図
:example-caption: 例
:table-caption: 表
:appendix-caption: 付録
:toc-title: 目次
:listing-caption: リスト
（略）
また、章節には通し番号がつくよう、 第1部の前に :sectnums: を設定します。その後、付録の前で :sectnums!: で番号がつかない設定に戻しています。
（略）
:sectnums:
= ここが第1部のタイトル
（略）
:sectnums!:
[appendix]
= 最初の付録
asciidoctor-pdf コマンドを使って example03.pdf を作成します。
$ asciidoctor-pdf -r asciidoctor-pdf-cjk -a pdf-style=mystyle-theme.yml -a pdf-stylesdir=theme -a pdf-fontsdir=fonts example03.adoc
作成したPDFを表示すると、見出しに使われてるフォントが「源真ゴシック-P」に変わり、章節番号がついています。また、目次や付録のページでは、見出しが日本語に変わっています。
長くなりましたので、タイトルページ、テーブルや図のキャプションなどについては、続きで。