lovstudio-any2pdf

any2pdf — Markdown から高品質な PDF へ

このスキルは、Python の reportlab ライブラリを使用して、あらゆる Markdown ファイルを出版品質の PDF に変換します。実際の中国語の技術レポートを使った広範な試行錯誤を通じて開発され、単純な MD→PDF コンバーターが正しく処理できない、いくつかの難しい問題を解決します。

使用するタイミング

• ユーザーが .md → .pdf への変換を希望している場合
• ユーザーが Markdown のレポートやドキュメントを持っていて、プロフェッショナルな組版を希望している場合
• ドキュメントにラテン文字と混在した CJK 文字（中国語／日本語／韓国語）が含まれている場合
• ドキュメントにフェンス付きコードブロック、Markdown の表、または入れ子のリストが含まれている場合
• ドキュメントにローカル／リモート画像、Obsidian のコールアウト、絵文字、または数式が含まれている場合
• ユーザーが PDF に表紙、目次、または透かしを入れたい場合

クイックスタート

python md2pdf/scripts/md2pdf.py \
  --input report.md \
  --output report.pdf \
  --title "My Report" \
  --author "Author Name" \
  --theme warm-academic

--input 以外のすべてのパラメーターは省略可能です。適切なデフォルト値が適用されます。

変換前のオプション（必須）

重要：変換を実行する前に、必ず AskUserQuestion ツールを使って、これらの質問をしてください。オプションをプレーンテキストで列挙してはいけません。ツールを使って、ユーザーに適切な対話形式のプロンプトを表示してください。すべてのオプションを、1 回の AskUserQuestion 呼び出しで尋ねてください。

次のテンプレートを使って AskUserQuestion を呼び出してください。堅苦しい設定フォームではなく、デザインアシスタントのように、親しみやすく簡潔な口調にしてください。

开始转 PDF！先帮你确认几个选项 👇

━━━ 📐 设计风格 ━━━
 a) 暖学术    — 陶土色调，温润典雅，适合人文/社科报告
 b) 经典论文  — 棕色调，灵感源自 LaTeX classicthesis，适合学术论文
 c) Tufte     — 极简留白，深红点缀，适合数据叙事/技术写作
 d) 期刊蓝    — 藏蓝严谨，灵感源自 IEEE，适合正式发表风格
 e) 精装书    — 咖啡色调，书卷气，适合长篇专著/技术书
 f) 中国红    — 朱红配暖纸，适合中文正式报告/白皮书
 g) 水墨      — 纯灰黑，素雅克制，适合文学/设计类内容
 h) GitHub    — 蓝白极简，程序员熟悉的风格
 i) Nord 冰霜 — 蓝灰北欧风，清爽现代
 j) 海洋      — 青绿色调，清新自然
 k) LaTeX 清爽 — pandoc+XeLaTeX 原生排版，无封面无装饰，干净学术风（需装 pandoc+texlive）
 l) 咨询深蓝  — 深海军蓝色块 + 白底 + 大写左对齐标题，麦肯锡 / BCG / Deloitte 研究报告风格

━━━ 🖼 扉页图片（封面之后的全页插图） ━━━
 1) 跳过
 2) 我提供本地图片路径
 3) AI 根据内容自动生成一张

━━━ 💧 水印 ━━━
 1) 不加
 2) 自定义文字（如 "DRAFT"、"内部资料"）
    可选调整：字号(默认52)、透明度(0-1)、角度(默认35°)、间距

━━━ 📇 封底物料（名片/二维码/品牌） ━━━
 1) 跳过
 2) 我提供图片
 3) 纯文字信息

示例回复："a, 扉页跳过, 水印:仅供学习参考, 封底图片:/path/qr.png"
直接说人话就行，不用记编号 😄

ユーザーの選択を CLI 引数に対応付ける

選択肢	CLI 引数
デザインスタイル a-k	--theme に以下の表の値を指定（k は pandoc エンジンを使用）
前付けページ（ローカル）	--frontispiece <path>
前付けページ（AI）	先に画像を生成し、その後 --frontispiece /tmp/frontispiece.png を指定
透かしのテキスト	--watermark "文字"
透かしのスタイル	--wm-size 30 --wm-opacity 0.1 --wm-angle 45（すべて省略可能）
表紙として画像を使用	--image-cover true（--frontispiece が必要）
裏表紙の画像	--banner <path>
裏表紙のテキスト	--disclaimer "声明" および／または --copyright "© 信息"

テーマ名の対応表

選択肢	--theme の値	着想元
a) 温かみのある学術風	warm-academic	Lovstudio design system
b) クラシックな論文	classic-thesis	LaTeX classicthesis
c) Tufte	tufte	Edward Tufte の書籍
d) 学術誌ブルー	ieee-journal	IEEE の学術誌形式
e) 装丁本	elegant-book	LaTeX ElegantBook
f) 中国レッド	chinese-red	中国の公式文書
g) 水墨画	ink-wash	水墨画／水墨画
h) GitHub	github-light	GitHub の Markdown スタイル
i) Nord	nord-frost	Nord の配色
j) オーシャン	ocean-breeze	—
k) すっきりした LaTeX	latex-clean	pandoc+XeLaTeX によるネイティブ組版、表紙なし
l) コンサルティング・ネイビー	consulting-navy	McKinsey／BCG／Deloitte のディープリサーチレポート

AI 生成の前付けページの処理

ユーザーが AI 生成を選んだ場合は、ドキュメントのタイトルと冒頭の段落を読み、画像生成ツールを使って、選択されたデザインスタイルに合ったテーマイラストを作成し、承認を得てから、--frontispiece /path/to/image.png で指定してください。

アーキテクチャ

Markdown → Preprocess (split merged headings) → Parse (code-fence-aware) → Story (reportlab flowables) → PDF build

主なコンポーネント：

1. フォントシステム：macOS では本文のラテン文字に Palatino、本文の CJK 文字に Songti SC、コードに Menlo を使用します。Linux では自動的に代替フォントに切り替わります
2. CJK ラッパー：_font_wrap() は CJK 文字の連続部分を <font> タグで囲み、フォントを自動的に切り替えます
3. 混在テキストレンダラー：_draw_mixed() はキャンバス上の CJK／ラテン文字が混在するテキスト（表紙、ヘッダー、フッター）を処理します
4. コードブロックハンドラー：esc_code() は reportlab の Paragraph でインデント、行中の位置合わせ、改行を保持します
5. スマートなテーブル幅：コンテンツの長さに基づいて列幅を比例配分し、最小幅を 18mm にします
6. ブックマークシステム：ChapterMark フローワブルが PDF のサイドバーブックマークと名前付きアンカーを作成します
7. 見出しプリプロセッサー：_preprocess_md() は # Part## Chapter のように結合された見出しを別々の行に分割します
8. 画像ハンドラー：ローカル、相対パス、file://、リモートの Markdown 画像を本文のフレーム内に収まるよう拡大縮小し、エラー時には代替テキストを表示します
9. コールアウトレンダラー：Obsidian 形式の > [!NOTE] ブロックを、テーマに沿った枠付きコールアウトとして描画します
10. 数式レンダラー：ディスプレイ数式にはオプションで matplotlib の mathtext 画像を使用し、利用できない場合はスタイル付きテキストで代替します
11. 絵文字のフォールバック：利用可能な場合はキャッシュされた Twemoji PNG として絵文字を描画し、それ以外の場合はローカルの絵文字フォントで代替します

試行錯誤から得た教訓

CJK 文字が □ として描画される

reportlab の Paragraph は ParagraphStyle で指定されたフォントのみを使用します。fontName="Mono" でも、テキストに中国語が含まれていると □ として描画されます。対策：コードブロックを含め、CJK 文字を含む可能性のあるすべてのテキストに必ず _font_wrap() を適用します。

コードブロックの改行が失われる

reportlab は \n を空白として扱います。対策：esc_code() は \n を <br/> に、すべてのスペースを   に変換し、_font_wrap() の適用前にインデントと行中の位置合わせを保持します。

CJK／ラテン文字のワードラップ

reportlab のデフォルトではスペースでのみ改行されるため、「Claude\nCode」のような不自然な分割が発生します。対策：本文と箇条書きのスタイルに wordWrap='CJK' を設定し、CJK 文字の境界でも改行できるようにします。

CJK 文字を含むキャンバス上のテキスト（表紙／フッター）

ラテン文字用フォントを指定して drawString()／drawCentredString() を使うと、年／月／日などを描画できません。対策：キャンバス上のユーザーコンテンツのテキスト（日時、統計情報、免責事項）にはすべて _draw_mixed() を使います。

画像が通知なく除外される（相対パス）

Markdown ファイル内の ![alt](charts/chart_01.png) は、画像パスが Markdown ファイルのディレクトリではなく現在の作業ディレクトリを基準に解決されていたため、警告もなく除外されていました。対策：main() は .md ファイルのディレクトリである input_dir をビルダーに渡すようになり、画像ハンドラーは相対パスをそのディレクトリを基準に解決します。画像が見つからない場合も、通知なく除外するのではなく、stderr に WARN: image not found: ... を出力するようになりました。

複数行の画像参照（pandoc --wrap=auto）

pandoc の出力を md2pdf に渡す際、pandoc のデフォルトである --wrap=auto（72 列）が長い ![alt text very long](path.png) を複数行に折り返すため、1 行の画像正規表現では処理できませんでした。対策：_preprocess_md() は解析前に（コードフェンスの外で）複数行の画像参照を 1 行にまとめるようになりました。

**パイプラインのヒント：**HTML から pandoc 経由で Markdown に変換する場合は、画像やテーブルの折り返しに起因する解析の問題を避けるため、pandoc --wrap=none input.html -o output.md を使用してください。

入力形式

このスキルの入力として使用できるのは Markdown ファイルのみです。HTML、DOCX、その他の形式の場合は、まず Markdown に変換してください（例：pandoc --wrap=none）。 Markdown 内の埋め込み HTML ブロックはテキストとして渡されます。md2pdf を実行する前に、グラフや複雑なテーブルなどの視覚的なコンテンツを、プレーンな Markdown テーブルまたは画像参照に変換してください。

設定リファレンス

ほとんどのオプションは、ファイル冒頭の YAML 形式のフロントマターでも設定できます。明示的な CLI 引数はフロントマターの値より優先されます。

Argument	Frontmatter Key	Default	Description
--input	—	(必須)	Markdown ファイルのパス
--output	—	output.pdf	出力 PDF のパス
--title	title	最初の H1 から取得	表紙に表示するドキュメントのタイトル
--subtitle	subtitle	""	サブタイトルのテキスト
--author	author	""	著者名
--date	date	今日の日付	日付文字列
--version	version	""	表紙に表示するバージョン文字列
--watermark	watermark	""	透かしのテキスト（空の場合はなし）
--theme	theme	warm-academic	カラーテーマ名
--theme-file	—	""	カスタムテーマ JSON ファイルのパス
--cover	cover	true	表紙を生成する
--toc	toc	true	目次を生成する
--page-size	page-size	A4	ページサイズ（A4 または Letter）
--frontispiece	frontispiece	""	表紙の後に配置する全ページ画像
--banner	banner	バンドルされた assets/backcover-banner.jpg	裏表紙のバナー画像（無効にするには none を指定）
--header-title	header-title	""	ページヘッダーに表示するレポートのタイトル
--footer-left	footer-left	author	フッターに表示するブランド名／著者名
--stats-line	stats-line	""	表紙に表示する統計情報
--stats-line2	stats-line2	""	2 行目の統計情報
--edition-line	edition-line	""	表紙下部に表示する版の表記
--disclaimer	disclaimer	""	裏表紙の免責事項
--copyright	copyright	""	裏表紙の著作権表記
--code-max-lines	code-max-lines	30	コードブロックごとの最大行数
--image-cover	image-cover	false	フロントピースを全面画像の表紙（1 ページ目）として使用する（テキスト表紙は 2 ページ目になります）
--heading-top-spacer	heading-top-spacer	5	H1／H2 の章タイトルの前に設ける上部余白（mm）
--wm-size	wm-size	自動（ページ幅の半分）	透かしのフォントサイズ。テキスト幅がページ幅の約 50% になるよう自動調整されます
--wm-opacity	wm-opacity	0.1	透かしの不透明度（0.0～1.0）
--wm-angle	wm-angle	35	透かしの回転角度（度）
--wm-spacing-x	wm-spacing-x	9999	透かしの水平方向の間隔（pt）。2000 以上の場合、各ページ中央に 1 つだけ配置されます
--wm-spacing-y	wm-spacing-y	9999	透かしの垂直方向の間隔（pt）。2000 以上の場合、各ページ中央に 1 つだけ配置されます

テーマ

利用可能なテーマ：warm-academic、nord-frost、github-light、solarized-light、 paper-classic、ocean-breeze、consulting-navy。

各テーマでは、ページの背景色、文字色、アクセントカラー、薄い文字色、枠線、コードの背景色、透かしの色合いを定義します。

フォールバック：pandoc + XeLaTeX

reportlab で問題が発生した場合（例：幅広または複雑な表によって表の幅の計算が無限ループになる場合）は、pandoc と XeLaTeX に切り替えます。これにより、表が適切に処理された高品質な CJK PDF が生成されます。

pandoc エンジンを使用する場合

• ユーザーが latex-clean テーマ（k）を選択した場合。pandoc がメインエンジンであり、フォールバックではありません
• 幅広の複数列テーブルが多数ある場合（reportlab の表レイアウトが停止する可能性があります）
• LaTeX 品質の組版（両端揃え、ハイフネーション）が必要な場合
• reportlab の md2pdf.py が入力の処理中に停止またはクラッシュする場合

基本コマンド

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Songti SC" -V mainfont="Palatino" -V monofont="Menlo" \
  -V geometry:margin=2.5cm -V fontsize=11pt \
  --toc -V toc-title="目录" -V documentclass=article

透かし＋ヘッダー／フッターの追加

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Songti SC" -V mainfont="Palatino" -V monofont="Menlo" \
  -V geometry:margin=2.5cm -V fontsize=11pt \
  -V colorlinks=true -V linkcolor=red -V toccolor=red -V urlcolor=red \
  --toc -V toc-title="目录" -V documentclass=article \
  -V header-includes='
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{\small 页眉左侧文字}
\fancyhead[R]{\small 页眉右侧文字}
\fancyfoot[C]{\thepage}
\usepackage{draftwatermark}
\SetWatermarkText{水印文字}
\SetWatermarkScale{0.5}
\SetWatermarkColor[gray]{0.9}
'

Pandoc テーマプリセット

各プリセットでは、Pandoc の -V フラグ一式が定義されています。上記の 「透かし＋ヘッダー／フッターの追加」のコマンド全体を使用し、プリセットに応じて色／リンクのフラグを置き換えてください。

テーマ	linkcolor	toccolor	urlcolor	透かしの色	備考
chinese-red	red	red	red	[gray]{0.9}	朱色で格式があり、官公庁・企業の報告書や白書に適しています
warm-academic	brown	brown	brown	[gray]{0.9}	テラコッタ調の、温かみのあるアカデミックなスタイルです
classic-thesis	brown	brown	brown	[gray]{0.85}	LaTeX classicthesis に着想を得ています
ieee-journal	blue	blue	blue	[gray]{0.9}	厳格な濃紺の、学術誌スタイルです
github-light	blue	blue	blue	[gray]{0.92}	ミニマルな青と白の配色で、プログラマーに適しています
ink-wash	black	black	black	[gray]{0.92}	水墨画のように素朴で上品な、文学・デザイン向けのスタイルです
nord-frost	teal	teal	teal	[gray]{0.9}	北欧風の氷を思わせる青灰色です
consulting-navy	blue	blue	blue	[gray]{0.88}	コンサルティング向けの濃紺で、調査報告書のスタイルです

chinese-red の完全な例（今回の一滕プロジェクトで実際に使用）

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Songti SC" -V mainfont="Palatino" -V monofont="Menlo" \
  -V geometry:margin=2.5cm -V fontsize=11pt \
  -V colorlinks=true -V linkcolor=red -V toccolor=red -V urlcolor=red \
  --toc -V toc-title="目录" -V documentclass=article \
  -V header-includes='
\usepackage{fancyhdr}
\pagestyle{fancy}
\fancyhf{}
\fancyhead[L]{\small 报告标题 | 品牌名}
\fancyhead[R]{\small 商业机密}
\fancyfoot[C]{\thepage}
\usepackage{draftwatermark}
\SetWatermarkText{商业机密}
\SetWatermarkScale{0.5}
\SetWatermarkColor[gray]{0.9}
'

latex-clean の完全な例（最もシンプルな LaTeX アカデミックスタイル）

latex-clean を選ぶ場合は、reportlab をスキップし、pandoc で直接生成してください。特徴：表紙なし、扉ページなし、 装飾的な色ブロックなし。LaTeX による組版と点線の目次リーダーのみで、内容を重視するアカデミック／技術文書に適しています。

pandoc input.md -o output.pdf \
  --pdf-engine=xelatex \
  -V CJKmainfont="Songti SC" -V mainfont="Palatino" -V monofont="Menlo" \
  -V geometry:margin=2.5cm -V fontsize=11pt \
  -V colorlinks=true -V linkcolor=brown -V toccolor=brown -V urlcolor=brown \
  --toc -V toc-title="目录" -V documentclass=article

ヘッダー、フッター、または透かしを追加する場合は、上記の「透かし＋ヘッダー／フッターの追加」を参照し、-V header-includes を追加してください。

既知の制限事項（pandoc フォールバック）

• 表紙はありません（pandoc の article クラスには組み込みの表紙がありません。必要な場合は LaTeX スニペットを --include-before-body とともに使用してください）
• 扉絵／裏表紙はサポートされていません（これらには md2pdf.py を使用してください）
• → ★ ☆ の記号は Palatino で警告が表示されることがあります。CJK フォントへのフォールバックで描画されるため、無視して問題ありません
• ASCII アートの図はコードブロックとして描画されます（md2pdf.py と同じです）

依存関係（pandoc フォールバック）

pandoc と XeLaTeX を含む TeX ディストリビューションが必要です。

brew install pandoc
brew install --cask mactex-no-gui   # or basictex

依存関係

pip install reportlab --break-system-packages
# Optional formula rendering:
pip install matplotlib --break-system-packages

推奨 Ubuntu／Debian フォント：

sudo apt install fonts-dejavu-core fonts-liberation fonts-freefont-ttf fonts-noto fonts-noto-cjk fonts-noto-color-emoji