Markdown を出版向けフォーマットに変換する

Markdown は開発者、ライター、オープンソースコミュニティにとっての共通言語となっています。プレーンテキストの構文は書きやすく、バージョン管理もしやすく、さまざまなプラットフォームでレンダリング可能です。しかし、ほとんどの読者は洗練された PDF、レスポンシブな HTML ページ、あるいは EPUB 電子書籍を期待しています。Markdown をこれらの下流フォーマットへ変換する際に、見出し・表・コードブロック・メタデータを失わずに行うのは意外と手間がかかります。本ガイドでは、忠実性・パフォーマンス・プライバシーのバランスを取った再現可能なワークフローを順に解説します。

ソース素材の理解

変換を始める前に、Markdown ファイルを「完成したドキュメント」ではなく「ソース文書」として扱います。特別な取り扱いが必要になる要素を洗い出しましょう。

  • フロントマター（メタデータ）（タイトル、著者、日付、タグ）。多くの静的サイトジェネレータでは --- で区切られた YAML 形式で記述されます。下流フォーマットでは表紙や埋め込みメタデータに利用されるため、必ず保持してください。
  • 言語識別子付きコードフェンス。技術書では構文ハイライトが必須です。
  • 表、脚注、定義リスト。すべてのターゲット形式がネイティブにサポートしているわけではないので、HTML の <table> や PDF の表構造にマッピングする必要があります。
  • 相対パスで参照される画像・アセット。変換パイプラインはこれらのパスを解決し、場合によってはバイナリデータを埋め込む必要があります。
  • 内部リンク（例：[Section](#section)）や 文書横断参照。単一の PDF や EPUB を生成する場合、機能するブックマークやハイパーリンクに変換すべきです。

これらの観点を事前にカタログ化しておくと、パイプライン後半での予期せぬ問題を防げます。

適切な変換エンジンの選択

Markdown 用のコンバータは大きく 3 つの系統に分かれます。

  1. Pandoc 系パイプライン – Pandoc は Markdown を読み込み、PDF、HTML、EPUB、DOCX など多数の形式へ出力できる汎用ドキュメントコンバータです。引用・脚注・カスタムテンプレートの取り扱いに優れています。
  2. 静的サイトジェネレータ（SSG） – Hugo、Jekyll、MkDocs などはテーマシステムを介して Markdown を HTML に変換します。フル機能のウェブサイトが必要なときに最適ですが、ヘッドレスな印刷ツールと組み合わせることも可能です。
  3. Web ベースサービス – convertise.app などは REST エンドポイントを提供し、Markdown を送るだけで所望の形式を返してくれます。ソフトウェアをインストールせずに一回限りの変換を行う場合に便利です。

再現性とプライバシーを重視するなら、ローカルに Pandoc をインストールして使用する方法を推奨します。処理はユーザーのマシン上だけで完結し、リモートサーバに痕跡を残しません。

環境の整備

  1. Pandoc（最新安定版）と、PDF 出力を行う場合は LaTeX ディストリビューション（例：TinyTeX）をインストール。
  2. 仮想環境（Python の venv や Node の nvm）を作成し、補助ツールを分離。
  3. アセットの集約 – 参照している画像・PDF・フォントをすべて単一フォルダにコピー。パス解決がシンプルになります。
  4. メタデータファイルの作成 – Markdown にフロントマターが無い場合は、metadata.yaml に title、author、date など埋め込みたい項目を書きます。
---
title: "Effective Open‑Source Documentation"
author: "Jane Doe"
date: "2026-05-10"
keywords: [markdown, documentation, publishing]
---

このブロックを各ソースファイルの先頭に付与するか、pandoc の --metadata-file オプションで渡します。

PDF への変換

Step 1: LaTeX テンプレートを選ぶ

Pandoc は PDF 出力時に内部で LaTeX を利用します。適切に設計されたテンプレートは余白・ヘッダー・フッター・フォント・コードブロックの描画を制御します。公式の eisvogel テンプレートは次の点で定評があります。

  • listings パッケージを使った構文ハイライト付きコードブロックに対応
  • クリック可能な目次を生成
  • XMP パケットにメタデータを埋め込める（デジタルライブラリ向け）

テンプレートをダウンロードし、アセットと同じディレクトリに配置してください。

Step 2: Pandoc を適切なフラグで実行

pandoc main.md \
  --metadata-file=metadata.yaml \
  --template=eisvogel.tex \
  --toc \
  --highlight-style=pygments \
  --pdf-engine=xelatex \
  -V mainfont="Libre Baskerville" \
  -V monofont="Fira Code" \
  -o output.pdf

主なオプションの意味

  • --toc … 自動的に目次を作成します。
  • -V mainfont / -V monofont … PDF の見た目を統一するためのフォント指定です。
  • --highlight-style … コードフェンスの色付けを一貫させます。

Step 3: 結果の検証

PDF を開き、以下を確認してください。

  • 目次にすべての見出しが掲載され、ページ番号が正しい
  • コードブロックが読みやすく、言語固有の色が保持されている
  • 画像が埋め込まれており（リンクではなく）比例的にスケーリングされている
  • メタデータ（作者・タイトルなど）が文書プロパティに表示されている（「ファイル → プロパティ → 説明」）

要素が欠けている場合はテンプレートを調整するか、pandoc-citeproc などのフィルタを追加してください。

HTML への変換

HTML はほとんどの Markdown エンジンのデフォルト出力ですが、出版品質を求める場合は 余計なクラスが付与されていないクリーンなマークアップ が必要です。

Step 1: 最小限の CSS フレームワークを選択

軽量なスタイルシートとして Pure.css や自作の style.css を使うと、ページは高速ながら表・ブロック引用・コードのデフォルトスタイルが整います。生成された HTML と同じディレクトリに CSS を置きましょう。

Step 2: Pandoc で HTML を生成

pandoc main.md \
  --metadata-file=metadata.yaml \
  --standalone \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o output.html
  • --standalone … 完全な HTML 文書（<html>・<head>・<body> を含む）を出力します。
  • --toc … ナビゲーションサイドバーとして目次を挿入します（CSS で固定位置にスタイリング可能）。

Step 3: アクセシビリティの向上

  • <html> タグに lang="en" を付与（lang=en を指定すれば Pandoc が自動で付加）。
  • すべての画像に alt 属性があるか確認。Markdown に記述が無い場合は Pandoc フィルタか手動編集で追加。
  • 見出しレベルが階層的（h1 → h2 → h3）であることをチェック。

Step 4: ブラウザでテスト

output.html を Chrome、Firefox、Edge で開き、狭いビューポートでもコードブロックが横スクロールでき、目次がスムーズに折りたためるか確認します。Chrome DevTools の Lighthouse で性能・アクセシビリティのスコアも測定してください。

EPUB（電子書籍）への変換

EPUB は XHTML、CSS、メタデータを ZIP 圧縮したものです。Pandoc が複雑さを隠蔽し、整ったパッケージを生成してくれます。

Step 1: EPUB メタデータを調整

--epub-metadata オプションで ID・出版社・言語情報を埋め込みます。簡易的な epub-metadata.xml を作成してください。

<?xml version="1.0" encoding="UTF-8"?>
<dc:metadata xmlns:dc="http://purl.org/dc/elements/1.1/">
  <dc:title>Effective Open‑Source Documentation</dc:title>
  <dc:creator>Jane Doe</dc:creator>
  <dc:language>en</dc:language>
  <dc:identifier id="bookid" opf:scheme="ISBN">978-3-16-148410-0</dc:identifier>
  <dc:publisher>Self‑Published</dc:publisher>
</dc:metadata>

Step 2: EPUB オプション付きで Pandoc を実行

pandoc main.md \
  --metadata-file=metadata.yaml \
  --epub-metadata=epub-metadata.xml \
  --toc \
  --css=style.css \
  --highlight-style=pygments \
  -o book.epub

目次は e‑book のナビゲーションファイルに変換され、CSS によりデバイス横断で統一された見た目が保証されます。

Step 3: EPUB の検証

オープンソースのバリデータ epubcheck を使って、リンク切れ・画像未配置・XHTML の不正構造を検出します。

java -jar epubcheck.jar book.epub

報告された問題は必ず修正し、Kindle Direct Publishing などの配信プラットフォームへアップロードできる状態にしましょう。

アセット埋め込みとパス解決の取り扱い

Markdown では相対パスで画像を参照することが多いです（例：![](images/logo.png)）。変換時に 外部リンクではなく埋め込み したいケースが特に PDF と EPUB では重要です。

  • Pandoc の --resource-path でアセット検索ディレクトリを指定。
  • --extract-media=./media を付与すると、リンクされたメディアが media ディレクトリにコピーされ、マークアップが自動で書き換えられます。
  • PDF 用には LaTeX エンジンに --pdf-engine-opt=--shell-escape を渡すと外部ファイルのインクルードが許可されます。

単一ファイルの自己完結型 HTML が欲しい場合は、pandoc --self-contained か wget --convert-links などのポストプロセスを利用してください。

各形式でのコードハイライトの保持

開発者向けドキュメントでは統一された構文ハイライトが不可欠です。

  • Pandoc は pygments、kate、tango など複数のハイライトスタイルをサポート。PDF と HTML の両方で見栄えが良いものを選びます。
  • PDF ではハイライトが LaTeX の listings または minted に変換されます。minted を使う場合は --pdf-engine-opt=-shell-escape と Python の pygments パッケージが必要です。
  • EPUB ではハイライトがインライン CSS の <span class="hlkwd"> などに展開されるので、CSS に対応するスタイル規則を記述しておきます。

独自配色が必要なときは、pygmentize -S <style> -f html -a .code でスタイルシートを生成し、CSS に組み込みましょう。

Makefile でのワークフロー自動化

各形式ごとに同じコマンドを手動で実行するとミスが起きやすくなります。シンプルな Makefile を用意すれば再現性が保証されます。

SOURCES = main.md metadata.yaml
ASSETS  = $(wildcard images/*)

PDF    = output.pdf
HTML   = output.html
EPUB   = book.epub

all: $(PDF) $(HTML) $(EPUB)

$(PDF): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --template=eisvogel.tex \
	  --toc \
	  --highlight-style=pygments \
	  --pdf-engine=xelatex \
	  -V mainfont="Libre Baskerville" \
	  -V monofont="Fira Code" \
	  -o $@

$(HTML): $(SOURCES) $(ASSETS)
pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --standalone \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

$(EPUB): $(SOURCES) $(ASSETS)
	pandoc $$(filter %.md,$^) \
	  --metadata-file=metadata.yaml \
	  --epub-metadata=epub-metadata.xml \
	  --toc \
	  --css=style.css \
	  --highlight-style=pygments \
	  -o $@

clean:
	rm -f $(PDF) $(HTML) $(EPUB)

make ひとつで 3 種類の出力が生成され、すべて同一のソースファイルから作られることが保証されます。

convertise.app のようなクラウドサービスを使うタイミング

ローカルに LaTeX 環境が無い、または一時的なマシンで変換したいときは、オンラインコンバータが重い処理を肩代わりしてくれます。データを メモリ上だけで処理し、長期保存しない ことが保証されていればプライバシー面でも問題ありません。汎用的な変換エンドポイントへの POST リクエスト例は以下の通りです。

POST https://convertise.app/api/convert
Content-Type: multipart/form-data

---
Content-Disposition: form-data; name="file"; filename="main.md"
Content-Type: text/markdown

<Markdown content>
---
Content-Disposition: form-data; name="target"

pdf
---

レスポンスとして変換済み PDF のバイナリストリームが返ってきます。単発のタスクには便利ですが、再現性のある出版パイプラインではローカルの Pandoc ソリューションが最も透明かつ監査しやすいです。

各形式での忠実度テスト

変換後は自動チェックを実施します。

  1. チェックサム比較 – ソース Markdown の SHA‑256 ハッシュを生成し、出力ファイルと同梱。ビルド間でソースが変更されていないことを証明できます。
  2. リンク検証 – pandoc --filter pandoc-citeproc で内部参照がすべて解決できているか確認。
  3. 画像ラスタライズテスト – PDF と EPUB を別々のビューアで開き、画像が期待通りの DPI（印刷は通常 300 dpi、画面表示は 72 dpi）でダウンサンプリングされていないか確かめます。
  4. アクセシビリティ監査 – PDF 用に pdfaPilot、HTML 用に axe-core などで alt テキスト欠如や見出し順序の問題を検出。
  5. スペルチェック – 生成された HTML または pdftotext で抽出したテキストに対し aspell・hunspell を走らせ、フィルタが引き起こす誤変換を捕捉。

これらのチェックを CI パイプライン（GitHub Actions、GitLab CI 等）に組み込めば、コミットごとに検証済みの出版資産が自動的に生成されます。

ワークフローまとめ

  1. ソース Markdown とアセットを集める。不足しているフロントマターは追加。
  2. 変換エンジンを選択（フルコントロールが必要なら Pandoc が推奨）。
  3. 各ターゲット形式用のテンプレートと CSS を設定。
  4. 変換コマンドを実行 – PDF は LaTeX、HTML は最小 CSS、EPUB はメタデータ付きで生成。
  5. 出力を検証 – チェックサム、リンク整合性、アクセシビリティ、目視確認。
  6. Makefile または CI で自動化し、プロセスの再現性を確保。

このレシピに従えば、単一の Markdown ソースから開発者向けガイド、学術ハンドブック、あるいは配信用 e‑book まで、出版品質のドキュメントを一貫して生成できます。

本稿で紹介した手法は、convertise.app のようなプライバシー重視のサービスとも併用可能です。ローカルツールが利用できない環境では、オンデマンド変換エンドポイントとして活用してください。