気軽にドキュメントを書くシリーズです。
asciidocで書き、asciidoctor-pdfでさくっとPDFにするというソリューションがあるようなので試行錯誤を繰り返した結果、この.adocをこのPDFに変換できるようになりました。
使い方ではまった箇所をメモしておきます。
インストール
githubのREADMEに書いてある通り、gemでインストールするだけ。
$ gem install --pre asciidoctor-pdf
デフォルトのテーマでPDFに変換する
asciidoctor-pdfコマンドを利用します。
$ asciidoctor-pdf basic-example.adoc
自作テーマを利用してPDFに変換する
Asciidoctor PDF Theming Guideに記載されている通り、自分なりのテーマを作ることができます。テーマを自作するにあたっては、デフォルトテーマの記載内容が参考になります。
今回はbasic-theme.ymlを作りました。ファイルはresources/themes配下に配置されています。
$ tree
.
|-- build.sh
|-- README.adoc
|-- README.pdf
|-- README.pdfmarks
`-- resources
|-- fonts
|-- images
`-- themes
|-- basic-theme.yml
`-- header-img-10mm.png
自作テーマを利用するためには、asciidoctor-pdfコマンドの-aオプションで、pdf-stylesdirとpdf-styleを指定します。
asciidoctor-pdf -a pdf-stylesdir=/resources/themes -a pdf-style=basic README.adoc
ページ番号を振る
ヘッダーとフッターにページ番号を振ることができます。今回は、.adocに:pagenums:を設定した上で、テーマファイルにページ番号の具体的なスタイルを記載します。
$ more README.adoc
= ほげほげサービス仕様書
ほげほげ株式会社 <doc.writer@example.jp>
v1.0, 2014-01-01
:toc:
:toc-title: 目次
:figure-caption: 図
:table-caption: 表
:toclevels: 2
:pagenums:
:sectnums:
:imagesdir: resources/images/
== はじめに
今回はフッターの真ん中にページ番号を表示してみましょう。
footer:
font_size: $base_font_size_small
font_color: $base_font_color
border_color: dddddd
border_width: 0.25
height: 25mm
padding: [3mm,0,0,0]
valign: top
recto_content:
center: '{page-number} / {page-count}'
verso_content:
center: '{page-number} / {page-count}'
このようにフッターにページ番号が表示されます。今回はフッターにページ番号を付与しましたが、ヘッダーに付与することも可能です。
ヘッダーやフッターに画像を追加する
ヘッダーやフッターに画像を追加することが可能です。まずは。追加したい画像をテーマと同じディレクトリに配置します。
$ tree
.
|-- build.sh
|-- README.adoc
|-- README.pdf
|-- README.pdfmarks
`-- resources
|-- fonts
|-- images
`-- themes
|-- basic-theme.yml
`-- header-img-10mm.png
そして、以下の様に設定します。今回はrecto_content_rightに画像を表示します。
header:
font_size: $base_font_size_small
font_color: $base_font_color
border_color: dddddd
border_width: 0.25
height: 25mm
padding: [0,0,3mm,0]
valign: bottom
image_valign: 50
recto_content:
left: '{document-title}'
right: image:header-img-10mm.png[width="75"]
verso_content:
left: '{document-title}'
ヘッダの右に画像が表示されました。ただしverso_content_rightにはimageを指定していないので、右ページには画像が出ますが、左ページには画像が出ません。
フォントを指定する
デフォルトでは以下3種類のフォントが利用可能です。これら以外のフォントを利用することも可能です。
- NotoSerif
- Mplus1mn
- Mplus1pMultilingual
Mplus1pMultilingual にはboldがないので、migmix-1pを利用してみましょう。
今回はresources/fonts配下にフォントを配置します。
$ tree
.
|-- build.sh
|-- README.adoc
|-- README.pdf
|-- README.pdfmarks
`-- resources
|-- fonts
| `-- migmix-1p
| |-- ipag00303
| | |-- IPA_Font_License_Agreement_v1.0.txt
| | `-- Readme_ipag00303.txt
| |-- migmix-1p-bold.ttf
| |-- migmix-1p-regular.ttf
| `-- migmix-README.txt
|-- images
`-- themes
|-- basic-theme.yml
`-- header-img-10mm.png
テーマファイルでmigmixを使うことを宣言します。
font:
catalog:
migmix:
normal: migmix-1p/migmix-1p-regular.ttf
bold: migmix-1p/migmix-1p-bold.ttf
italic: migmix-1p/migmix-1p-regular.ttf
bold_italic: migmix-1p/migmix-1p-bold.ttf
fallbacks:
- migmix
page:
background_color: ffffff
layout: portrait
margin: [30mm, 30mm, 30mm, 30mm]
size: A4
base:
font_color: 000000
font_family: migmix
asciidoctor-pdfコマンドの-aオプションでpdf-fontsdirを指定します。
asciidoctor-pdf -a pdf-stylesdir=/resources/themes -a pdf-style=basic -a pdf-fontsdir=/resources/fonts README.adoc
所感
- PDFは綺麗に描画された。
- 描画に至るまでの準備が簡単
- テーマのスタイルファイルは独自形式なので、CSSでの装飾と比べると自由度は狭い。
- たとえば、現在の私の力では、テーブルの横幅を縮めることができない。[width=”50″]で表の横幅が50%になるはずなのだが、PDFに表示される表の横幅は100%になってしまいまう
- 必要最低限に装飾したPDFを作る分にはもってこいかも