pandocでMarkdownからEPUBを作る（連載⑦）

pandocでMarkdownからEPUBを作る — Kindle本ビルドパイプライン（連載⑦）

「日本の測地系がわかる本」制作の裏側を綴る連載、第7回です。前回は書籍図版をmatplotlibスクリプトで作る話を書きました。今回は、書き上げた原稿（Markdown）をKindleで読めるEPUBに変換するビルドパイプラインについて整理します。

原稿はMarkdown、変換は pandoc

本の原稿は、ブログ記事と同じように Markdownで書いています。章ごとに1ファイルとし、見出しレベルを次のルールで統一しました。

#（H1）＝章
##（H2）＝節

pandocはこの見出し構造から、目次と章区切り（改ページ）を自動生成します。手動でページ区切りを入れる必要がないため、原稿はレイアウトを気にせず文章に集中して書けます。

書誌情報は metadata.yaml という別ファイルにまとめます。

---
title: 日本の測地系がわかる本
subtitle: 地図の座標はなぜズレるのか。TOKYOからJGD2024まで
author: Y4U
language: ja
publisher: （個人出版名義）
rights: © 2026 y4u
cover-image: ../images/ch00-cover.png
---

タイトル・著者・表紙画像の指定などをここに集約しておくと、EPUB生成コマンドが1行で済みます。

ビルドコマンドは1行

実際のビルドコマンドは次の形です。

pandoc manuscript/metadata.yaml manuscript/[0-9]*.md \
  -o build/geodetic-book.epub \
  --toc --toc-depth=2 \
  --epub-chapter-level=1 \
  --css=manuscript/style.css

manuscript/[0-9]*.md というファイル名規則（00-front.md 01-ch00-intro.md …）にしているので、ファイル名の連番がそのまま本の掲載順になります。
--epub-chapter-level=1 で、H1（章）を単位にEPUBの章分割を行います。
style.css は最小限に留めています。表の罫線・引用の囲み・コラム用のクラス程度で、凝った装飾はKindle端末側で崩れることがあるためです。

落とし穴：カバー画像の相対パスとCWD

パイプラインを組んでいて実際にハマったのが、カレントディレクトリ（CWD）とカバー画像の相対パスの関係です。metadata.yaml の cover-image: ../images/ch00-cover.png は、manuscript/ フォルダを基準にした相対パスとして書いています。ところが、リポジトリのルートなど別の場所から pandoc コマンドを実行すると、この相対パスの基準がずれて画像が見つからず、pandocがexit 1で終了するという事態になりました。

原因は単純で、pandocの相対パス解決がコマンド実行時のCWD基準になっているためです。対策として、必ず manuscript/ フォルダに cd してからビルドコマンドを実行するという運用ルールに統一しました。CI化するなら、ビルドスクリプトの先頭で cd を固定するか、--resource-path オプションで明示的に検索パスを指定しておくと安全です。

品質チェックはepubcheckで機械的に

EPUBが生成できたら、次の記事で詳しく書くepubcheckによるチェックを毎回通しています。ここでは概要だけ触れると、

epubcheck build/geodetic-book.epub

を実行し、エラー・警告がゼロになるまで原稿かCSSか画像を直して再ビルドする、というサイクルを回しています。

PDF版はweasyprintで別ビルド

EPUBとは別に、紙のレイアウトに近いPDF版も欲しくなったため、weasyprint を使ってMarkdownから直接PDFを生成するビルドも用意しました。PDF専用の print.css を追加し、A4サイズ・余白・CJKフォント指定・章の先頭改ページなどを設定しています。EPUB用の style.css に加えて --css=manuscript/print.css を指定し、--pdf-engine=weasyprint を渡すだけで、同じMarkdown原稿から異なる出力形式を作れるのは、Markdown一本化のメリットを実感した場面でした。