Marp CLI による PDF 作成

はじめに

ここ最近、技術発表などのスライドは Marp を使って作成することが多いです。編集には Visual Studio Code の Extension（Marp for VS Code）を用いますが、commit したタイミングで PDF が自動生成されると便利なのではないかと思い、前段階として CLI による PDF 作成の方法を調べました。

PDF 作成の例として、自分が先日実施した研修（Markdown for Beginners）の原稿を使用します。原稿は以下のリポジトリにあります。

Kenichi TAGI / sp-workshop · GitLab

この中の、 markdown-beginners/ に原稿一式が揃っています。今回はこれをサンプルに使用します。

markdown-beginners/
├── example.md
├── images/
│   ├── babel.png
│   ├── markdown-flow.png
│   ├── markdown-mark-solid.svg
│   ├── markdown-mark.svg
│   └── marp.png
├── markdown-beginners.drawio.xml
├── markdown-beginners.md
└── markdown-beginners_tips.md

手順

嬉しいことに Marp CLI は Docker イメージとして公開されています。

an official Docker image marpteam/marp-cli

ローカルで実行する場合は Node や Chrome が必要となります。インストールの手間を省きたい、ローカル環境を汚したくないので今回はこの Docker イメージを使用することにします。

Marp CLI イメージの入手

Docker Hub から Marp CLI のイメージを pull します。

$ docker pull marpteam/marp-cli

$ docker images
REPOSITORY                     TAG                 IMAGE ID            CREATED             SIZE
marpteam/marp-cli              latest              5736e75c625b        2 days ago          538MB

サンプル原稿の入手

上記リポジトリから clone します。

$ git clone https://tech.jspnet.biz/gitlab/tagi/sp-workshop.git

コンテナの起動・実行

まず、原稿のある sp-workshop/markdown-beginners/ に移動します。

$ cd sp-workshop/markdown-beginners

ここで空（0 バイト）の出力ファイルを作成します。原稿となる入力ファイルは markdown-beginners.md なので、出力ファイルは markdown-beginners.pdf となります。

$ touch markdown-beginners.pdf

次にこの出力ファイルのアクセス権を変更し、誰でも書き込めるようにします。

$ chmod o+w markdown-beginners.pdf

$ ls -l markdown-beginners.pdf
-rw-rw-rw- 1 tagi tagi 0 11月  6 14:15 markdown-beginners.pdf

これで準備完了。コンテナを起動して Marp CLI を実行します。

$ docker run --rm --init \
    -v /usr/share/fonts/:/usr/share/fonts/ \
    -v $PWD:/home/marp/app/ \
    -e LANG="ja_JP.UTF-8" \
    marpteam/marp-cli markdown-beginners.md --pdf --allow-local-files

できあがりです。

$ ls -l markdown-beginners.pdf
-rw-rw-rw- 1 tagi tagi 1326745 11月  6 14:19 markdown-beginners.pdf

解説

公式の手順との違いを解説します。

公式の手順:

$ docker run --rm --init \
    -v $PWD:/home/marp/app/ \
    -e LANG=$LANG \
    marpteam/marp-cli slide-deck.md --pdf

出力ファイルの作成

コンテナ内部では marp ユーザが PDF ファイルを生成（出力）するようになっています。ところがホスト側では marp ユーザなど知らないので新しくファイルを生成しようとすると失敗（EACCES）します。なので、ここでは予め誰でもアクセス可能な出力ファイルを作っておき、そこに出力させています。

MEMO: 本来であればサンドボックス的な場所にバインドマウントして作業するのが筋かも？

フォント問題

現在公開中のイメージには適切な日本語フォントが入っていません。公式の手順では日本語が中華フォントで作成されてしまいました。なので /usr/share/fonts/ をバインドマウントして、ホストのフォントを使用するようにしています。また、自身の LANG 環境変数 は en_US.UTF-8 だったので ja_JP.UTF-8 を明示しています。

ローカルファイルへのアクセス

原稿となる markdown-beginners.md では画像も表示するため images/ ディレクトリ内のイメージファイルを参照しています。--allow-local-files オプションを与えることにより、ローカルファイル（images/）へのアクセスを許可しています（このオプションは Marp CLI に対しての指示）。

ちなみにこのオプションを付与しない場合、画像の抜けた不完全な PDF ができあがります。

おわりに

Marp CLI は PDF の他にも HTML や PPTX にも変換できるようです。リポジトリに push したら Marp CLI で HTML 化して静的サイト（GitHub Pages とか）に展開、なんてことができると嬉しいのかも。

今回使用したスライドは SlideShare にもアップしています。