PDF Creator

マークダウンから中国語フォント対応とテーマシステムを備えたプロフェッショナルなPDFドキュメントを作成します。

クイックスタート

# デフォルトテーマ（フォーマル: Songti SC + 黒/グレー、A4印刷）
uv run --with weasyprint scripts/md_to_pdf.py input.md output.pdf

# ウォームテーマ（トレーニング: PingFang SC + テラコッタ）
uv run --with weasyprint scripts/md_to_pdf.py input.md --theme warm-terra

# モバイルテーマ（狭いページ、大きいフォント — 携帯読書 / WeChat共有用）
uv run --with weasyprint scripts/md_to_pdf.py input.md --theme mobile

# すべてのマークダウンファイルを特定のテーマでバッチ変換
uv run --with weasyprint scripts/batch_convert.py *.md --theme warm-terra --no-preview

# weasyprint未導入？ Chromeバックエンドを使用（weasyprint未利用時は自動選択）
python scripts/md_to_pdf.py input.md --theme warm-terra --backend chrome

# 利用可能なテーマをリスト表示
python scripts/md_to_pdf.py --list-themes dummy.md

テーマ

themes/*.css に保存されています。各テーマはスタンドアロンのCSSファイルです。

テーマ	ページサイズ	フォント	色	最適な用途
default	A4	Songti SC + Heiti SC	黒/グレー	法務文書、契約書、フォーマルレポート
cjk-auto	A4	Songti SC + Heiti SC	黒/グレー	不均等な列幅のテーブル（時間割、項目リスト）
warm-terra	A4	PingFang SC	テラコッタ (#d97756) + ウォームニュートラル	コース概要、トレーニング資料、ワークショップ
mobile	148mm × 210mm	PingFang SC	テラコッタ + ウォームニュートラル	携帯読書、WeChat共有、外出先での参照

新しいテーマを作成するには、themes/default.css をコピーして編集し、themes/your-theme.css として保存します。

プリント vs モバイル：正しいテーマを選択

シナリオ	推奨テーマ	理由
A4紙に印刷、ハンドアウト、契約書	default	標準ページサイズ、フォーマルなタイポグラフィ
トレーニング資料、コース概要	warm-terra	ウォームなアクセント色、ワークショップコンテキストで読みやすい
WeChat経由で送信、携帯で読む	mobile	狭いページ（148mm）、15pxフォント、1.9行間隔 — 小さい画面で快適
プリントとモバイル両方が必要	異なるテーマで2回実行	スクリプトは高速です。両方のバージョンを生成します

決定ルール： ユーザーが指定しない場合、トレーニング/コースコンテンツは warm-terra、フォーマルな文書は default をデフォルトとします。出力チャネルが不明な場合のみ「是否需要手机版？」と質問してください。

バックエンド

スクリプトは利用可能な最適なバックエンドを自動検出します：

バックエンド	インストール	メリット	デメリット
weasyprint	pip install weasyprint	正確なCSS描写、ブラウザ不要	システムライブラリ（cairo、pango）が必要
chrome	Google Chrome インストール済み	Pythonの依存なし、優れたCJK対応	バイナリが大きい、CSS制御がやや限定的

--backend chrome または --backend weasyprint でオーバーライドします。

バッチ変換

# デフォルトテーマ、同じディレクトリ
uv run --with weasyprint scripts/batch_convert.py *.md

# 特定のテーマ、出力ディレクトリ、速度向上のためプレビュースキップ
uv run --with weasyprint scripts/batch_convert.py *.md --theme warm-terra --output-dir ./pdfs --no-preview

# 携帯読書用のモバイルテーマ
uv run --with weasyprint scripts/batch_convert.py *.md --theme mobile --output-dir ./mobile-pdfs --no-preview

アンチパターン：pandoc + Chrome を手動で呼び出さない

このスキルが存在する理由： 手動の pandoc input.md -o out.html + chrome --headless --print-to-pdf ワークフローは、検出が難しい方法で静かに失敗します：

手動ステップ	何が間違っていくか	このスキルの修正
pandoc -o out.html	CJK対応CSS なし → 中国語の空白/ボックス表示	CJKフォントスタック + タイポグラフィパッチを注入
Chrome --print-to-pdf	デフォルトヘッダー/フッター表示（ファイル名、日付、URL、ページ番号）	--no-pdf-header-footer を渡す
レンダリング後のチェック未実施	「終了コード0」で成功と仮定。レンダリングバグが隠れている	ページ別PNG プレビュー自動生成 + タイポグラフィ検査
テーマシステムなし	一律対応；携帯読書不可能	3つの厳選テーマ（default / warm-terra / mobile）
batch_convert.py なし	アドホックループ、フラグの不整合	--theme 対応の組み込みバッチモード

ルール： ユーザーがPDF変換を要求する場合、常にこのスキルを使用してください。pandoc/Chrome コマンドで手動で回避しないでください。

トラブルシューティング

中国語文字がボックスとして表示される: 中国語フォント（Songti SC、PingFang SC など）がインストールされていることを確認します。

weasyprint インポートエラー: uv run --with weasyprint で実行するか、代わりに --backend chrome を使用します。

コードブロック内のCJKテキストが文字化けている（weasyprint）: スクリプトは中国語/日本語/韓国語文字を含むコードブロックを自動検出し、CJK対応フォントのスタイル付きdivに変換します。まだ問題が見られる場合は、ネイティブCJK対応の --backend chrome を使用してください。別の方法として、PDFを生成する前にコードブロックをマークダウンテーブルに変換します。

Chrome ヘッダー/フッターが表示される: スクリプトは --no-pdf-header-footer を渡します。それでも表示される場合、お使いのChrome バージョンがこのフラグに対応していない可能性があります — Chrome を更新してください。注記： このスキルを回避して手動でChrome headless を使用した場合、これが最初の兆候です — 上記の「アンチパターン」セクションを参照してください。

インラインコードが混在 CJK + ASCII を表示（macOS Preview で空白） 例えば `Terminal/终端` は Terminal/ のみ表示され、CJK部分が欠落します：weasyprint は PingFang SC を OpenType（CID Type 0C） としてサブセット埋め込みており、厳密なPDFリーダー（macOS Preview / Adobe Reader）はレンダリング失敗します。Chrome の PDF ビューア は自動的にフォールバックし、バグを隠します。修正はデフォルトテーマにあります：コードフォント-family チェーンは CID TrueType CJK フォント（Songti SC / Heiti SC）を OpenType フォント（PingFang SC）の前に優先化します。検証するには：pdfplumber + CJK 文字の font['fontname'] を確認します — CID Type 0C OT を参照する PingFang-SC があれば、リーダーはおそらく失敗します。フォント チェーンを再度並べてCID TrueType を最初に配置します。

テーブル列1で短いラベルが途中で折れている 例えば 4/28（周|二）下|午：pandoc は markdown セパレータ行のダッシュ数から <colgroup><col style="width:X%"> を自動生成します。| ----- | --- | --- | -------- |（ダッシュ幅が不均等）の場合、pandoc は列1に約17%を割り当てます — 9文字のCJKラベルには狭すぎます。インライン style="" は外部CSSと同じ特異性で勝つため、td:first-child { width:... } は静かに影で隠れます。修正はデフォルトテーマにあります：table colgroup col { width: auto !important } は pandoc のヒントを中和し、table-layout: fixed が均等分布できるようにします（4列テーブルの場合は列あたり25%）。検証するには：pandoc input.md -t html | grep colgroup — <col style="width:X%"> が表示される場合、バグは適用されます。スコープ： 中和剤は default.css にのみあります。warm-terra と mobile テーマは異なるストラテジー（th/td上の nowrap と last-child wrap、および完全フロー wrap）を使用し、意図的にこれを省略しています。中和剤は scripts/tests/test_cjk_tables.py::test_default_theme_neutralizes_pandoc_colgroup_hint でロックされています。

視覚的自己チェック（必須 — スキップしないでください）

これはオプションではありません。 PDF生成のたびに、スクリプトは自動的に：

1. pdftoppm（poppler-utils）を介して各ページをPNG に変換し、PDF の隣の <pdf-name>-preview/ ディレクトリに保存します
2. 各ページを視覚的に検査するよう呼び出し元に促す構造化された自己チェックチェックリストを印刷します
3. CJK 行区切りのアンチパターンを検出するためにタイポグラフィ検査を実行します

必須である理由： 「PDFが正常に生成された」≠「レンダリングがマークダウンインテントと一致」。一般的な静かな失敗の例：

• 段落が1つに折りたたまれている（連続する非空行上の CommonMark ソフト改行）
• テーブルがページマージンをオーバーフロー
• CJK / 絵文字グリフが欠落
• コードブロック文字化け
• Chrome デフォルトヘッダー/フッター（このスキルを回避した場合）

ワークフロー： スクリプト実行後、各 page-NN.png を読み、マークダウンソースと照合します。何かがインテントと異なる方法でレンダリングされる場合、マークダウンを修正 してください（疑似リストではなく - の実リストを使用、空行を挿入、テーブルを再構成）し、再実行します。スクリプトは非標準マークダウンを黙って「修正」しません — それはソースが間違っているというシグナルをマスクします。同じマークダウンが他のプロセッサ（Obsidian、GitHub、VS Code プレビュー）で正しくレンダリングされないことが原因です。

バッチ/非対話的実行の場合は --no-preview で無効化：

python scripts/md_to_pdf.py input.md output.pdf --no-preview

必須： pdftoppm（macOS では brew install poppler）。インストールされていない場合、スクリプトはヒントをログに記録し、プレビュー生成をスキップしますが、それでもPDFを生成します。

CJK タイポグラフィ（デフォルト動作）

スクリプトは2つのレイヤーの CJK 対応処理を自動的に適用します — ユーザーのマークダウンソースやテーマCSS ファイルを変更しません：

レイヤー1：CSS パッチ（自動注入、約80%のケースを修正）

_load_theme() は読み込まれたテーマCSSにCJK タイポグラフィCSSパッチを追加します。パッチは：

• table { table-layout: fixed; width: 100% } — 等しい列幅は weasyprint 自動レイアウトが隣の列に5倍のコンテンツがある場合に1列を約10%の幅に圧縮することを防止
• td, th { word-break: keep-all; overflow-wrap: normal; line-break: strict } — CJK文字を分割しません。overflow-wrap: normal（break-word ではなく）によってエンコードされた意図的なトレードオフは、トークン中の改行へのフォールバックよりもコンテンツを多少オーバーフロー させることです — 理由は md_to_pdf.py L109-146 のインラインコメントに記載され、scripts/tests/test_cjk_tables.py でロックされています
• th { white-space: nowrap } — 短いヘッダーは予測可能な列幅のために1行のままです

これはユーザーのソースに触れずに、最も一般的なアンチパターン（CJK文字間に強制折り返されたセル内容から単一文字のみの行を生成）を静かに修正します。ユーザーのテーマCSSファイルはディスク上で変更されません。

レイヤー2：タイポグラフィ検査（レンダリング後検出、残りをキャッチ）

PDF生成後、スクリプトはページごとに pdftotext -layout を実行し、「中文文案排版指北」（中国語タイポグラフィスタイルガイド）に従って既知の CJK アンチパターンをスキャンします：

• 行だけに単一のCJK文字（セルは依然としてレイヤー1の後でも狭い）
• （ で終わる行が次の行にコンテンツが続く（壊れた括弧ペア）
• ) で始まる行（前の括弧ペアから壊れている）
• 中途半端な句読点 、，；： で終わる短い行

検出結果は stderr にページ+行位置付きで出力されます。これらは エラーではなく警告です — PDF はまだ生成されます。著者は次を決定します：

1. 受け入れる（例えば、長いドキュメント内の1つの孤立した文字は許容可能な場合があります）
2. オフェンディングセルコンテンツを短縮して列幅に合わせる
3. 再構成する（例えば、長いコンテンツをテーブル下の段落に移動）

なぜすべてを黙って自動修正しないのですか？

レイヤー2 は意図的にマークダウンを変更しません。CLAUDE.md の「禁止隠式行為」ルールに従って：非標準マークダウン（疑似リストを実リストに拡張するなど）を静かに書き直すと、ソースが間違っているというシグナルをマスクします。同じマークダウンが他のプロセッサで正しくレンダリングされないことが原因です。レイヤー1 は受け入れられます。既に標準的なマークダウン（weasyprint が CJK に対して不完全にレンダリングする標準的なテーブル）ではなく、マークダウンソース自体をレンダリング 動作 をパッチするためです。

既知の制限事項

単一セルのコンテンツが利用可能な列幅よりもわずかに長い場合（例えば、等分割後に9文字幅のセルに10個のCJK文字）、weasyprint は keep-all にもかかわらず強制改行にフォールバックします。レイヤー1 はこれを修正できません — レイヤー2 はこれをキャッチし、著者がセルコンテンツを短縮するか、再構成するよう促します。