コマンドからmarkdownを印刷用PDFに変換する（pandocとBasicTeX）

pandocでMarkdownをPDFに書き出すと、内部では一度LaTeXのソースに変換してからコンパイルしている。
BasicTeXは最小構成のTeX Live配布なので、日本語パッケージを自分で追加する必要がある。
日本語を扱うにはlualatexとluatexjaの組み合わせが必要で、pdflatexのままでは進めない。
スタイルはYAMLファイルに分けて書けて、–metadata-fileと–defaultsという二つの方法がある。

1. pandocは、内部でMarkdownをLaTeXに変換している

Typoraなどのアプリで直接PDF化しようとすると、起動が重かったり過去に開いたファイルが勝手に立ち上がったりして煩わしい。そこでコマンドラインからpandocでPDFに書き出す方法を試すことにした。

pandocはMarkdownを直接PDFにしているわけではありません。内部ではまずMarkdownをLaTeXのソースに変換し、それをTeXエンジンでコンパイルしてPDFを生成しています¹。つまりpandocは変換の入口で、実際に組版しているのはLaTeX側。

この仕組みに気づいたのは、日本語を含む原稿を変換したときでした。実行すると、見たことのない数のエラーが流れてきます。原因はBasicTeXにありました。 BasicTeXはmacOS向けのTeX Live配布ですが、名前の通り最小構成で、日本語組版に必要なパッケージが最初から入っていません²。フルセットのMacTeXなら困らない部分ですが、容量が数GBにもなるため、記事執筆用の環境としてはBasicTeXを選ぶ人が多いはずです。

では、日本語を通すにはどうすればいいのか。 BasicTeXに日本語パッケージを追加インストールし、日本語対応のTeXエンジンを指定してやる必要があります。ここから先は、その二段構えの対応を順番に見ていきます。

2. BasicTeXに日本語パッケージを追加する

2.1. 追加パッケージのインストール

BasicTeXにはtlmgr（TeX Live Manager：TeX Liveのパッケージを管理するコマンド）が付属しています。これを使って、日本語組版に必要なパッケージ群を追加します。

sudo tlmgr update --self --all
sudo tlmgr install collection-langjapanese collection-luatex collection-latexextra
Code language: PHP (php)

collection-langjapaneseが日本語フォントと日本語用のクラスファイル、collection-luatexがLuaLaTeX関連の一式、collection-latexextraがそのほか周辺パッケージをまとめてインストールしてくれます³。何も考えずに素のBasicTeXで日本語原稿を変換すると、この時点でエラーになる。最初にこのパッケージ群を入れておかないと、後の作業がすべて空振りに終わります。

2.2. エンジンとフォントの選び方

パッケージを入れても、まだ終わりではありません。 pandocがPDF生成に使うTeXエンジンには何を選ぶかという問題が残っています。

pdflatexは長らくLaTeXの標準的なエンジンでしたが、日本語の縦横比や禁則処理には対応していません⁴。そこで選択肢に上がるのがlualatexとxelatexです。 lualatexはluatexjaという日本語組版パッケージと組み合わせて使うのが定番で、documentclassにltjsarticleのような日本語対応クラスを指定します⁵。 xelatexを使う場合はxeCJKというパッケージが同じ役割を担いますが、フォント周りの挙動が少し異なる。どちらか一方に統一しておいたほうが、あとで混乱しません。

ヒラギノなどmacOSに標準で入っているフォントを使いたい場合、TeX側からシステムフォントを見えるようにする作業も必要です⁶。

sudo /usr/local/texlive/2025basic/bin/universal-darwin/cjk-gs-integrate --link-texmf --force

パスの中のバージョン番号は環境によって変わるので、実際にインストールされているディレクトリ名を確認してから実行してください。ここまで済ませると、ようやく日本語入りのMarkdownがエラーなく変換できるようになります。

3. YAMLでスタイルを指定する

3.1. metadata-fileとdefaultsファイルの違い

documentclassやフォント名といった見た目の設定は、Markdownファイルの先頭にYAMLブロックとして直接書くこともできます。ただ、記事ごとに毎回同じ設定を書き写すのは手間です。そこで、スタイル情報だけを別のYAMLファイルに切り出して読み込む方法を使っています。

分ける方法は二通りあります。ひとつは–metadata-fileで、メタデータだけを別ファイルから読み込む方法⁷。もうひとつは–defaultsで、pdf-engineや入力ファイル名まで含めたコマンド全体をYAMLにまとめる方法です⁸。記事を量産する用途なら、defaultsファイルにまとめておくほうが扱いやすいと感じています。

3.2. よく使う項目

defaultsファイルの中では、documentclassやgeometryのようにLaTeXテンプレートへ渡す値はvariablesキーの下に、titleやlangのような文書そのものの情報はmetadataキーの下に置きます。 Markdown本文に直書きするYAMLブロックとの違いはここです。

実際に毎回設定しているのは、次のような項目です。

pdf-engine: lualatex

metadata:
  lang: ja

variables:
  documentclass: ltjsarticle
  classoption:
    - a4paper
    - 11pt
  geometry:
    - margin=2.5cm
  CJKmainfont: "Hiragino Kaku Gothic ProN"
  header-includes:
    - \usepackage[no-math, no-prompts]{luatexja-fontspec}
Code language: HTTP (http)

pdf-engineでlualatexを指定し、documentclassには日本語対応のltjsarticleを選ぶ。 CJKmainfontでヒラギノ角ゴを指定し、header-includesでluatexja-fontspecを読み込ませています⁹。この組み合わせを一度作ってしまえば、あとは記事を書くたびに同じファイルを読み込むだけで済みます。

3.3. 使用頻度が下がる項目

このほかにも、必要になったときだけ調べる項目がいくつかあります。 table-of-contentsとtoc-depthは目次の有無と階層の深さ、colorlinksとlinkcolorはPDF内のリンクの色付け、highlight-styleはコードブロックの配色を決めます。参考文献を扱う記事なら、bibliographyとcsl、citeprocの出番です。

titleやkeywordsのように記事ごとに変わる値は、あえてdefaultsファイルに含めていません。使い回すファイルと、記事固有のファイルを分けておいたほうが、あとで見返したときに迷わずに済みます。

4. 実際にコマンドを実行する

準備したdefaultsファイルをstyle.yamlという名前で保存しておくと、コマンドは次の一行で済みます。

pandoc article.md --defaults=style.yaml -o article.pdf

初めて実行したときは、フォントが見つからないというエラーに一度当たりました。 CJKmainfontに指定したフォント名の表記が、実際のフォント名と微妙に違っていたのが原因でした。 fc-listコマンドでシステムのフォント一覧を確認し、表示された名前をそのままコピーしてからは、エラーが出なくなりました。

書き出されたPDFを開くと、見出しも本文も日本語がきちんと組まれていて、拍子抜けするくらいあっさり片付きました。 Typoraを起動する手間も、過去のファイルが勝手に開く煩わしさも、もうありません。コマンド一つでPDFができる状態を作っておくと、記事を書くたびの小さなストレスが消えていく。仕組みを一度理解してしまえば、あとは同じ手順の繰り返しです。

pandoc公式マニュアルでは、PDF出力時はデフォルトでLaTeXを使用し、LaTeXエンジンのインストールが前提になると説明されている。 – Pandoc User’s Guide
TeX Users Group公式ページでは、BasicTeXはフルのTeX Liveを避けたいユーザー向けの、大幅に小さい代替ディストリビューションと説明されている。 – More Packages – MacTeX
collection-langjapaneseは、TeX Liveのパッケージリポジトリに日本語サポート用のコレクションとして登録されている。 – Cygwin Package Summary for texlive-collection-langjapanese
pandoc公式マニュアルでは、CJKmainfontを設定した場合、xelatex使用時はxeCJK、lualatex使用時はluatexjaが必要になると説明されている。 – Pandoc User’s Guide
LuaTeX-jaの公式リポジトリでは、日本語文書を作成する場合にltj{article,book,report}.clsやltjs{article,book,report}.clsの利用を検討するよう案内されている。 – GitHub – luatexja/luatexja
cjk-gs-integrateは、システム上のCJKフォントを検索し、Ghostscriptから利用できるようにするスクリプトとしてCTANで配布されている。 – CTAN: Package cjk-gs-integrate
pandoc公式マニュアルでは、–metadata-fileで読み込んだ内容からは、本文の脚注のようなコンテンツを参照できないと明記されている。 – Pandoc User’s Guide
pandoc公式マニュアルでは、–defaultsオプションはYAMLまたはJSON形式でオプション一式を指定するためのものと説明されている。 – 5 Defaults files – Pandoc User’s Guide
pandoc公式マニュアルでは、CJKmainfontはxelatexまたはlualatex使用時に和文フォントを指定する変数として説明されている。 – 6.2 Variables – Pandoc User’s Guide