lovstudio:any2pdf

any2pdf — Markdown を高品質な PDF に変換

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

使用する場面

• ユーザーが .md → .pdf への変換を希望している場合
• Markdown のレポートやドキュメントを、プロフェッショナルな組版で仕上げたい場合
• ドキュメントに CJK 文字とラテン文字が混在している場合
• ドキュメントにフェンス付きコードブロック、Markdown テーブル、またはネストされたリストが含まれている場合
• 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 デザインシステム
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（ラテン文字の本文）、Songti SC（CJK の本文）、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 のように連結された見出しを別々の行に分割します

試行錯誤から得た教訓

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 文字を含む Canvas のテキスト（表紙／フッター）

ラテン文字用フォントを使った drawString()／drawCentredString() では、年／月／日などを描画できません。修正：ユーザーコンテンツに関するすべての Canvas テキスト（日付、統計、免責事項）に _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 行にまとめるようになりました。

パイプラインのヒント： pandoc を介して HTML → Markdown に変換する場合は、画像や表で折り返しによる解析上の問題が発生しないよう、pandoc --wrap=none input.html -o output.md を使用してください。

入力形式

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

設定リファレンス

引数	デフォルト	説明
--input	(required)	Markdown ファイルへのパス
--output	output.pdf	出力 PDF のパス
--title	From first H1	表紙に表示するドキュメントのタイトル
--subtitle	""	サブタイトルのテキスト
--author	""	著者名
--date	Today	日付文字列
--version	""	表紙に表示するバージョン文字列
--watermark	""	透かしテキスト（空の場合はなし）
--theme	warm-academic	配色テーマ名
--theme-file	""	カスタムテーマの JSON ファイルパス
--cover	true	表紙を生成する
--toc	true	目次を生成する
--page-size	A4	ページサイズ（A4 または Letter）
--frontispiece	""	表紙の後に配置する全ページ画像
--banner	bundled assets/backcover-banner.jpg	裏表紙のバナー画像（無効にするには none を指定）
--header-title	""	ページヘッダーに表示するレポートのタイトル
--footer-left	author	フッターに表示するブランド名／著者名
--stats-line	""	表紙に表示する統計情報
--stats-line2	""	2 行目の統計情報
--edition-line	""	表紙下部のエディション行
--disclaimer	""	裏表紙の免責事項
--copyright	""	裏表紙の著作権表示
--code-max-lines	30	コードブロックあたりの最大行数
--image-cover	false	フロントページ画像を全面表示の表紙（1 ページ目）として使用し、テキストの表紙を 2 ページ目にする
--heading-top-spacer	5	H1／H2 の章タイトル前に設ける上部余白（mm）
--wm-size	auto (half page width)	透かしのフォントサイズ。テキスト幅がページ幅の約 50% になるよう自動調整します
--wm-opacity	0.1	透かしの不透明度（0.0～1.0）
--wm-angle	35	透かしの回転角度（度）
--wm-spacing-x	9999	透かしの水平方向の間隔（pt）。2000 以上の場合、ページごとに中央へ 1 つだけ配置します
--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 クラスには組み込みの表紙がありません。必要な場合は --include-before-body と LaTeX スニペットを使用してください）
• 扉ページ／裏表紙には対応していません（これらには md2pdf.py を使用してください）
• → ★ ☆ の記号は Palatino で警告が出ることがあります。CJK フォントへのフォールバックで描画されるため、無視して問題ありません
• ASCII アートの図はコードブロックとして描画されます（md2pdf.py と同じです）

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

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

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

依存関係

pip install reportlab --break-system-packages