pandoc + wkhtmltopdf + cssでマークダウンからgithub風レイアウトなpdfを作る for mac


はじめに

お仕事で設計書などのドキュメントを書く時にはExcelやWordなどOffice製品を駆使してきました。
皆さんがおそらく容易に想像できる色々な理由で、こんな欲が出てきました。

  • やっぱりドキュメントもコード管理したいよね
  • だけど、md読めない人もいるからpdfにはしたいよね
  • イメージとしてはTeXみたいな感じ、というかTeX最高だよね

というわけで、そんな欲望を満たせるpandocを使ってみようということになりましてそのセットアップ記録を残します。

環境

使うツールについて

wkhtmltopdfとは

HTMLをPDFに変換するツールです。
つまり、

wkhtmltopdf http://google.com google.pdf

で、googleのページをPDF化することができます。
後述のpandocと組み合わせることで、Markdown→HTML→PDFの流れで変換することが可能となります。

pandocとは

一言で言えば、多様なフォーマットに対応した超便利なドキュメントフォーマットツールです。
今回のケースではMarkdown→HTML→PDFで利用しますが、HTML→LaTeXとか、Textile→Word(docx)とかも対応してます。
詳しくは、公式ドキュメントをどうぞ。
ちなみに、日本語翻訳版ドキュメントがありますが、この訳者である@sky_yさんは僕の学生時代の先輩です(pandocを調べている時にたまたま見つけてびっくりしました笑 お世話になっております!)

組み合わせるってどうやって?

pandocで、Markdown→HTML→PDFの流れで変換すると説明しましたが、pandoc自体は元ファイルから作成ファイルを作る中間生成物としてHTMLを作成するようです。
今回の場合は、HTML→PDFに変換するときのエンジンとしてwkhtmltopdfを利用します。
つまり、例えば、pdfLaTeXを使えば、Markdown→HTML→LaTeX→PDFになるという理解です(違ってたらご指摘ください)。
ということは、単純にPDFにする目的だけなのであれば、wkhtmltopdfを使うことで処理も軽くできるということになるのかな?と思ってます。

やること

  • wkhtmltopdfのインストール
  • pandocのインストール
  • Github風レイアウトが実現できるcssをダウンロード
  • 変換元mdファイル作成
  • pdf変換

やってみた

wkhtmltopdfのインストール

Homebrewでインストールが可能です。

$ brew install --cask wkhtmltopdf

公式から直接ダウンロードも可能です。

pandocのインストール

Homebrewでインストール可能です。

$ brew install pandoc

Github風レイアウトが実現できるcssをダウンロード

こちらからダウンロードします。

変換元mdファイル作成

Markdownの具体的な書き方などについてはここでは触れません。
こんなファイル構造の前提で、ここから先を読んでください。

.
├── css
│   └── github.css # Github風レイアウトができるcss
├── documents
│   └── sample.md
└── pdf

ちなみに、今回pdfに変換するmdファイル(sample.md)はこちらです。

---
title: サンプルファイル
author: 私が著者だ
---

# はじめに
このファイルはQiita投稿用サンプルです

# やりたいこと
- いい感じにpdfを出力したい
- 元ファイルはMarkdownで書きたい

# やること
- 必要なものインストール
- pdf出力

## 必要なものインストール

```sh
brew install --cask wkhtmltopdf
brew install pandoc
```

## pdf出力

```sh
pandoc -o output.pdf sample.md
```

pdf変換

基本的には、以下の形式です。

$ pandoc <インプットファイルパス> -o <出力ファイルパス> --pdf-engine wkhtmltopdf <その他オプション>

ここでは、章番号の付与(-Nオプション)、目次の作成(--tocオプション)も付けてみます。
使えるオプションは、公式にありますので詳しくはこちらを参照ください

$ pandoc ./documents/sample.md -o ./pdf/output.pdf -N --toc -c ./css/github.css --pdf-engine wkhtmltopdf
Loading pages (1/6)
Counting pages (2/6)                                               
Resolving links (4/6)                                                       
Loading headers and footers (5/6)                                           
Printing pages (6/6)
Done

出力されたpdfはこんな感じ。PDFのプロパティとしてちゃんと目次が出力されるのでもはや--tocオプションは不要なのかもしれないなと思いました。

おわりに

それなりに見やすいPDFが、簡単に作成できるので体裁には特にこだわってなくてそれなりに綺麗であれば良ければなんの問題も無いと思います。
css職人になれば、もっと自分なりのカスタマイズもできますので拡張性は高いですね。
どんどん活用していこうと思います。