lov-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) 海洋      — 青绿色调，清新自然

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

━━━ 💧 水印 ━━━
 1) 不加
 2) 自定义文字（如 "DRAFT"、"内部资料"）

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

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

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

選択肢	CLI 引数
デザインスタイル a-j	表の値を指定した --theme
前付け画像（ローカル）	--frontispiece <path>
前付け画像（AI）	先に画像を生成し、その後 --frontispiece /tmp/frontispiece.png
透かしテキスト	--watermark "文字"
裏表紙の画像	--banner <path>
裏表紙のテキスト	--disclaimer "声明" および／または --copyright "© 信息"

テーマ名の対応表

選択肢	--theme の値	インスピレーション
a) 暖かみのあるアカデミック	warm-academic	Skill Publisher のデザインシステム
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	—

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 のように結合された見出しを個別の行に分割します
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 文字を含む Canvas テキスト（表紙／フッター）

ラテン文字用フォントを使った drawString()／drawCentredString() では、年／月／日などを表示できません。修正方法：日付、統計情報、免責事項など、ユーザーコンテンツの Canvas テキストすべてに _draw_mixed() を使用してください。

設定リファレンス

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

引数	フロントマターのキー	デフォルト	説明
--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	""	裏表紙のバナー画像
--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	コードブロックごとの最大行数

テーマ

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

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

依存関係

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

実行時コンテキスト（共有）

実行前に、この Skill パッケージの skill.yaml を読み込み、ホストが提供する skill-runtime/v1 コンテキストを使用します。フィールドの解決順序は、現在のリクエスト、プロジェクトコンテキスト、個人設定、ブランドプロフィール、汎用デフォルト値です。

• Manifest で宣言されたフィールドのみを使用します。Profile には公開されているブランド情報を保存し、Preferences には個人の作業上の好みを保存します。
• required: true のフィールドが不足している場合は、Manifest の質問設定に従って、焦点を絞った質問をユーザーに 1 つ提示します。ユーザーが明示的に同意した後で、回答を保存します。
• エラーには、コピー可能な context_id、フィールドのパス、情報源を含めます。診断内容には、秘密情報、個人の完全なパス、元の設定を含めないでください。