md-to-pdf

Markdown から PDF への変換

Markdown ファイルを、Mermaid 図、LaTeX 数式（KaTeX 経由）、表、シンタックスハイライト付きコードブロック、その他すべての標準的な Markdown 機能を完全にレンダリングした、プロフェッショナルなスタイルの PDF に変換します。

アーキテクチャ

Input .md file
     │
     ├─ Step 1: Extract ```mermaid blocks → render to SVG via mmdc (Mermaid CLI + Puppeteer)
     │          Replace mermaid code blocks with inline <svg> in the markdown source
     │
     ├─ Step 2: pandoc converts modified markdown → standalone HTML5
     │          (--katex flag preserves raw LaTeX in <span class="math ..."> elements)
     │
     ├─ Step 3: Node.js KaTeX server-side rendering
     │          Replaces math spans with fully rendered KaTeX HTML (no client-side JS needed)
     │
     ├─ Step 4: CSS injection
     │          KaTeX stylesheet (with local font paths) + professional document styles + optional custom CSS
     │
     └─ Step 5: Playwright (headless Chromium) prints final HTML → PDF
                 ↓
           Output .pdf file

対応機能

機能	レンダリングエンジン	備考
Mermaid 図	Puppeteer 経由の mmdc（mermaid-cli）	フローチャート、シーケンス図、クラス図、状態図、ER 図、ガントチャート、円グラフ、Git、マインドマップなど
LaTeX 数式（インライン）	サーバーサイドの KaTeX	$E=mc^2$ 構文
LaTeX 数式（ディスプレイ）	サーバーサイドの KaTeX	$$\int f(x) dx$$ 構文
表	pandoc + CSS	GFM のパイプテーブルを完全にサポートし、プロフェッショナルなスタイルで表示
コードブロック	pandoc + CSS	pandoc によるシンタックスハイライト、等幅フォントで表示
画像	pandoc + Playwright	ローカルの file:// とリモートの https:// の画像
リンク	pandoc	スタイル付きテキストとしてレンダリング
リスト／引用	pandoc	番号付き、番号なし、入れ子、引用
YAML フロントマター	pandoc	PDF のタイトルメタデータに title を使用
脚注	pandoc + CSS	[^1] 構文で記述し、ページ下部に表示
定義リスト	pandoc + CSS	用語と定義のペア
取り消し線	pandoc	~~deleted~~ 構文
水平線	pandoc + CSS	--- をスタイル付きの区切り線として表示

前提条件

初回使用前にセットアップチェッカーを実行してください。

bash <SKILL_DIR>/scripts/setup.sh

このチェッカーは、必要なすべてのツールが存在し、動作していることを確認します。標準の Claude コンピューター操作環境には、必要なものがすべてあらかじめインストールされています。その他の環境で必要なスタックは次のとおりです。

依存関係	用途	インストール方法
pandoc	Markdown → HTML	apt install pandoc
mmdc (@mermaid-js/mermaid-cli)	Mermaid → SVG	npm install -g @mermaid-js/mermaid-cli
katex (npm)	LaTeX → HTML	npm install -g katex
playwright (Python)	HTML → PDF	pip install playwright && playwright install chromium
Chrome/Chromium	ブラウザーエンジン	Playwright または Puppeteer によってインストールされます

使い方

基本

python3 <SKILL_DIR>/scripts/md_to_pdf.py <input.md> <output.pdf>

すべてのオプション

python3 <SKILL_DIR>/scripts/md_to_pdf.py <input.md> <output.pdf> [OPTIONS]

パラメーター	デフォルト	説明
input	(必須)	入力 Markdown ファイルのパス
output	(必須)	出力 PDF ファイルのパス
--format	A4	用紙サイズ：A4、Letter、Legal、A3
--margin	0.75in	余白 — 単一の値（均一）または top,right,bottom,left
--no-mermaid	false	Mermaid のレンダリングをスキップします（コードブロックをそのまま保持します）
--no-math	false	KaTeX 数式のレンダリングをスキップします
--css	(なし)	上に重ねる追加のカスタム CSS ファイルのパス
--landscape	false	横向きのページ設定
--header-footer	false	フッターにページ番号（ページ数／合計ページ数）を表示します

使用例

# Standard A4 conversion
python3 scripts/md_to_pdf.py report.md report.pdf

# US Letter, landscape, with page numbers
python3 scripts/md_to_pdf.py report.md report.pdf --format Letter --landscape --header-footer

# Custom margins and extra CSS
python3 scripts/md_to_pdf.py report.md report.pdf --margin "1in,0.75in,1in,0.75in" --css brand.css

# Plain mode (skip Mermaid + math for speed)
python3 scripts/md_to_pdf.py report.md report.pdf --no-mermaid --no-math

Claude のワークフロー

ユーザーから Markdown を PDF に変換するよう依頼された場合：

1. 入力ファイルのパスを特定します（アップロードされたファイルまたはユーザー指定のパス）
2. セッションで初めて使用する場合は、セットアップ確認を実行します：

   bash <SKILL_DIR>/scripts/setup.sh
   

3. 変換を実行します：

   python3 <SKILL_DIR>/scripts/md_to_pdf.py /path/to/input.md /path/to/output.pdf [OPTIONS]
   

4. 出力ファイルをユーザーに提示します

エラーへの対処

症状	考えられる原因	対処法
Mermaid の処理中に「mmdc FAILED」	Mermaid の構文が無効です	図の構文を確認します。解析エラーは mmdc の標準エラー出力に表示されます
PDF に生の LaTeX が表示される	KaTeX が式を解析できませんでした	LaTeX の構文を確認します。KaTeX は適切にフォールバックします
「No Chrome binary found」	Puppeteer／Playwright の Chromium がありません	playwright install chromium を実行します
図が空白または表示されない	SVG が大きすぎるか複雑すぎます	--no-mermaid を試し、図を個別にレンダリングします

カスタマイズ

カスタム CSS

--css path/to/custom.css を指定すると、デフォルトの後にスタイルを適用できます。指定したルールが優先されます。

例 — ダークテーマの上書き：

body {
  background: #1a1a2e;
  color: #e0e0e0;
}
h1,
h2,
h3 {
  color: #e0e0e0;
  border-color: #444;
}
table th {
  background: #2a2a4a;
}
pre {
  background: #0d0d1a;
  border-color: #333;
}

Mermaid のテーマ設定

MERMAID_CONFIG 環境変数に JSON 設定ファイルを指定します：

MERMAID_CONFIG=/path/to/.mermaidrc python3 scripts/md_to_pdf.py input.md output.pdf

.mermaidrc の例：

{
  "theme": "neutral",
  "themeVariables": {
    "primaryColor": "#e1f5fe",
    "lineColor": "#333"
  }
}

制限事項

• Mermaid 図のレンダリングには、CDN ベースの mmdc を利用するためのネットワークアクセス、またはローカルへの @mermaid-js/mermaid-cli のインストールが必要です。オフライン環境では --no-mermaid を使用し、図を個別にレンダリングしてください。
• 大きなドキュメント（100 ページ以上、または高解像度画像が多数含まれる場合）は、Playwright のメモリ制限に達することがあります。入力ファイルを複数に分割し、生成された PDF を結合してください。
• カスタム CSSは、PDF ビューアーによって同じようにレンダリングされない場合があります。レイアウトはレンダリング時に Chromium によって決まり、Acrobat Reader、Preview、ブラウザーでは同じ PDF でも表示が異なることがあります。
• 改ページには、明示的な CSS マーカー（page-break-before: always または break-before: page）か、ソース内の手動の <div style="page-break-before: always"> が必要です。Pandoc は見出し構造から改ページを推測しません。
• KaTeX の対応範囲は広いものの、完全ではありません。KaTeX がサポートするセットに含まれない珍しい LaTeX マクロやパッケージはレンダリングに失敗し、生の LaTeX にフォールバックします。

ファイル構成

md-to-pdf/
├── SKILL.md                    # This file — skill documentation
├── LICENSE.txt                 # MIT license
├── README.md                   # Distribution / standalone usage docs
├── scripts/
│   ├── md_to_pdf.py            # Main conversion pipeline (Python)
│   ├── katex_render.js         # Server-side KaTeX math renderer (Node.js)
│   └── setup.sh                # Dependency checker / installer
└── tests/
    └── test_document.md        # Comprehensive test covering all features