asciidocをPDFに変換してみた(asciidoctor-pdf)

Uncategorized
Published: 2015-07-01

気軽にドキュメントを書くシリーズです。

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を作る分にはもってこいかも