lov-any2pdf

PDFマスター · PDF Master

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

トリガー

次の場合に有効化

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

次の場合は有効化しない

• ユーザーが Markdown の内容の修正のみを希望しており、PDF 出力を必要としていない
• 入力元が HTML、DOCX、または別の形式で、ユーザーが Markdown への変換手順を許可していない
• ユーザーが PDF ではなく、スライド資料、編集可能な Word ドキュメント、または画像出力を必要としている

クイックスタート

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

--input 以外のすべてのパラメーターは省略可能です。テーマが指定されていない場合、レンダラーはドキュメントの内容と構成に基づいてテーマを選択します。

設定の解決（必須）

変換のたびに、すべての設定項目を並べたフォームを提示してはいけません。各設定は、次の順序で個別に解決してください。

1. 現在のリクエストでユーザーが明示した指示、次に CLI 引数またはドキュメントのフロントマター
2. lov_any2pdf 設定名前空間で、ユーザーが最後に明示的に確認した値
3. テーマについては内容に基づく判断、視覚要素以外の設定については文書化された安全なデフォルト値

これらの設定で変換内容が決まる場合は、確認せずに作業を進めてください。未解決の選択によって結果が大きく変わる場合（ローカルアセットのパスが不明な場合や、新しい画像を生成する許可が必要な場合など）に限り、簡潔な質問を最大 1 つしてください。ユーザーがテーマ一覧を明示的に求めていない限り、すべてのテーマから選ぶよう求めてはいけません。

ユーザーが再利用可能なパラメーターを明示的に確認または変更した後は、その値を最新の設定として記録してください。ユーザーから指定がない場合は、次回その値を再利用します。推測した値を、ユーザーが確認した値として保存してはいけません。また、保存済みの設定をリセットまたは無視するリクエストには従ってください。

再利用可能なパラメーターには、テーマ、表紙／目次、ページサイズ、口絵モード、ウォーターマークのテキストと配置、画像表紙モード、裏表紙モード／バナー、免責事項、著作権表示、ヘッダー、フッターが含まれます。保存済みのファイルパスは使用前に再検証してください。アセットが見つからない場合は、黙って別のものに置き換えず、代わりのものを指定するよう求めてください。

内容に基づくテーマの選択

現在のリクエストにも保存済みの設定にもテーマの指定がない場合は、タイトル、冒頭部分、見出し、ドキュメントの長さ、コードブロック、表、画像、出版の文脈を確認し、記事に最適なテーマを選択してください。以下は判断の手掛かりであり、キーワードによって固定的に振り分けるルールではありません。

内容の特徴	適したテーマの候補
長文の中国語文章、ナレッジメモ、情報量の多い表	songti-reading
戦略、ビジネス、市場、または調査レポート	consulting-navy
要旨／方法／結果／参考文献を含む学術論文	ieee-journal または classic-thesis
コード中心の技術ガイドまたは API ドキュメント	github-light
グラフや指標を含むデータの解説	tufte
文学、芸術、写真、またはデザインに関するエッセイ	ink-wash
正式な中国語の政策文書または機関文書	chinese-red
中立的な英語の文章または印刷を重視するドキュメント	paper-classic

warm-academic は記事の文調に本当に適している場合に引き続き利用できますが、ユーザーがスタイルを指定しなかったという理由だけでデフォルトにしてはいけません。

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

選択肢	CLI 引数
デザインスタイル	--theme に下表の値を指定します（latex-clean は 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 の値	インスピレーション
温かみのある学術	warm-academic	温かみのあるエディトリアル・アカデミックな配色
クラシックな論文	classic-thesis	LaTeX classicthesis
Tufte	tufte	Edward Tufte の書籍
ジャーナルブルー	ieee-journal	IEEE ジャーナル形式
上製本	elegant-book	LaTeX ElegantBook
中国レッド	chinese-red	中国の公式文書
水墨	ink-wash	水墨画
GitHub	github-light	GitHub Markdown スタイル
Nord	nord-frost	Nord カラースキーム
オーシャン	ocean-breeze	すっきりとしたティール系のエディトリアル配色
LaTeX クリーン	latex-clean	pandoc+XeLaTeX によるネイティブ組版、表紙なし
コンサルティングネイビー	consulting-navy	コンサルティング調査レポート
読みやすい宋体	songti-reading	中国語出版物で一般的な、本文に宋体、見出し階層に黒体を使用

AI 生成の口絵の扱い

ユーザーが AI 生成を選択した場合は、ドキュメントのタイトルと最初の数段落を読み、選択されたデザインスタイルに合うテーマのイラストを画像生成ツールで作成し、承認を得てから --frontispiece /path/to/image.png で渡します。

アーキテクチャ

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

主なコンポーネント：

1. フォントシステム：Palatino（ラテン文字の本文）、Songti SC Regular（CJK の本文）、選択可能なセリフ体／サンセリフ体の CJK 強調フォント、macOS では Menlo（コード）を使用します。Linux／Windows では自動的に代替フォントに切り替わります
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 文字の境界でも折り返せます。

明朝体の読書体裁にはサンセリフ体の階層が必要です

全体に同じサンセリフ体を使うと、中国語の密度の高いレポートが一様に暗い印象になり、 全体に明朝体を使うと見出しや表のヘッダーが弱くなります。修正：本文に Songti SC Regular、 ラテン文字の文章に Palatino、見出しと強調に中国語のサンセリフ体、コードに Menlo、 広めの行間、表の本文にセリフ体を使うsongti-readingテーマを使用します。すべてのレポートを 暗黙に変更するのではなく、明示的なテーマとして維持してください。

macOSでは、Songti.ttcのインデックス0はSongti SC Blackであり、Regularではありません。読みやすい書体は インデックス6です。✓、✗、→など、レポートでよく使われる記号には、明示的な記号フォントへの フォールバックが必要です。そうしないと、周囲の中国語が正しく表示されていても□として表示される場合があります。

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

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

画像が警告なしに除外される（相対パス）

Markdownファイル内のcharts/chart_01.pngへの画像参照は、画像パスがMarkdownファイルのディレクトリではなく、 現在の作業ディレクトリを基準に解決されていたため、以前は警告なしにスキップされていました。修正：main()が.mdの ディレクトリであるinput_dirをビルダーに渡すようになり、画像ハンドラーは相対パスをこのディレクトリを基準に解決します。画像が見つからない場合も、 黙って除外するのではなく、標準エラー出力にWARN: image not found: ...が出力されるようになりました。

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

pandocの出力をmd2pdfに渡すと、pandocの既定値である--wrap=auto（72列）によって、 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の表または画像参照に変換してください。

設定リファレンス

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

引数	フロントマターキー	デフォルト	説明
--input	—	(required)	Markdown ファイルのパス
--output	—	output.pdf	出力 PDF のパス
--title	title	最初の H1 から取得	表紙のドキュメントタイトル
--subtitle	subtitle	""	サブタイトルのテキスト
--author	author	""	著者名
--date	date	今日	日付文字列
--version	version	""	表紙に表示するバージョン文字列
--watermark	watermark	""	透かしテキスト（空の場合はなし）
--theme	theme	コンテンツに応じた auto	カラーテーマ名。明示的な設定と保存済みの設定が優先されます
--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	著者	フッターに表示するブランド名／著者名
--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 つ配置）

テーマ

利用可能なテーマ：songti-reading、warm-academic、nord-frost、github-light、 solarized-light、paper-classic、ocean-breeze、monokai-warm、 dracula-soft、tufte、classic-thesis、ieee-journal、elegant-book、 chinese-red、ink-wash、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

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

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

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

通用反馈闭环

用户在 Skill 驱动任务中提出修改意见时，继续当前产物前必须执行：

1. 先判断意见是 task-specific（仅本次）还是 reusable（可跨任务复用）。
2. task-specific 只修改当前任务，不改 Skill。
3. reusable 先确定作用域：领域规则先更新对应 canonical Skill；适用于所有 Skill 的规则先更新共享规范。
4. 完成规则更新、版本、lint 与分发核验后，再把修改应用到当前任务。
5. reusable 修改会使此前的“确认”“继续”“发吧”失效；完成当前产物修改和回读后必须停下，等待用户下一步指示，不自动进入发布、提交或其他外部写入。