Markdown → PowerPoint マッピング仕様
md-pptx が Markdown の各要素をどのように PowerPoint のプレースホルダにマッピングし、スタイルを適用するかの仕様です。
マッピング表
| Markdown | マッピング先 | スタイルの出所 | 備考 |
|---|---|---|---|
# h1（スライド内最初の h1/h2） | タイトルプレースホルダ | テンプレート: プレースホルダのデフォルトに完全委任 | コード側ではフォント属性を設定しない（#131） |
## h2（スライド内最初の h1/h2） | タイトルプレースホルダ | テンプレート: プレースホルダのデフォルトに完全委任 | 最初の h1/h2 は title PH にマッピングされる |
## h2 〜 ###### h6（2番目以降） | 本文プレースホルダ内 | コード側: bold + フォントサイズ / テンプレート: フォント種類・色を継承 | PowerPoint に見出しレベルの概念がないため |
| 段落テキスト | 本文プレースホルダ | テンプレート | レベル1の段落デフォルト |
- リスト | 本文プレースホルダ（段落レベル1） | テンプレート | 段落レベルの箇条書きスタイルに従う |
- ネストリスト | 本文プレースホルダ（段落レベル2〜） | テンプレート | インデント = 段落レベル対応 |
1. 番号リスト | 本文プレースホルダ（段落レベル1） | テンプレート | 同上 |
**bold** | ランレベルの書式 | Markdown | テンプレートに関係なく適用 |
*italic* | ランレベルの書式 | Markdown | 同上 |
 | 画像プレースホルダ（あれば） | テンプレート（位置・サイズ） | なければ本文エリア内に自由配置 |
レイアウト自動選択ロジック
layout ディレクティブが指定されていない場合、md-pptx はスライドの内容を分析して最適なレイアウトを自動選択します。
コンテンツ分析
スライド内の要素を以下の3つの観点で分析します。
- hasHeading —
h1またはh2の見出しを含むか - hasBody — 本文テキスト（段落、リスト、h3〜h6、テーブル、コードブロック）を含むか
- hasImage — 画像を含むか
選択フロー
コンテンツなし
→ "Blank"
本文のみ（見出しなし）
→ "Title and Content"（名前検索）
→ body プレースホルダを持つ任意のレイアウト
→ "Blank"
見出し + 本文 or 画像
→ "Title and Content"（名前検索）
→ title + body を持つ任意のレイアウト
→ "Blank"
見出しのみ
→ "Section Header"（名前検索）
→ "Title Slide"（名前検索）
→ title を持つ任意のレイアウト
→ "Blank"各段階で「名前ベース」→「プレースホルダ type ベース」の順にフォールバックします。
プレースホルダマッピング規則
レイアウトが決まった後、スライド内の各要素をプレースホルダに割り当てます。
割り当てルール
- 最初の h1/h2 → title プレースホルダ（なければ subtitle プレースホルダを代用）
- 画像 → picture プレースホルダ → body プレースホルダ（picture がない場合）
- その他のテキスト要素（段落、リスト、h3〜h6、テーブル、コードブロック） → body プレースホルダ
- title と subtitle の両方があり、title に見出しが割り当て済みの場合、残りのテキスト要素は subtitle に配置（body がない場合の退避先）
フォールバック規則
プレースホルダが見つかる場合:
タイトルPH あり → h1/h2 をタイトルPHに
本文PH あり → 本文・リスト・h3〜h6 を本文PHに
画像PH あり → 画像を画像PHに
すべての要素がマッピングできなかった場合:
（マッピング成功 = 0 件 かつ 未マッピング要素あり）
→ Blank レイアウトにフォールバック
→ 全コンテンツをコード側の座標で自由配置
（フォントサイズ・位置すべてコード側のデフォルト値）
一部の要素だけマッピングできた場合:
マッピングされた要素のみ出力される
未マッピング要素は出力されない（Blank フォールバックは発生しない）見出しのフォントサイズ
タイトルプレースホルダ（h1/h2）
タイトルプレースホルダにマッピングされる h1/h2 は、フォントスタイル（サイズ、太字、色、フォント種類）をすべてプレースホルダのデフォルトに委任します。コード側ではテキストの注入のみ行い、フォント属性は一切設定しません。テンプレートのスライドマスターで定義されたスタイルがそのまま適用されます。
本文プレースホルダ（h2〜h6）
本文プレースホルダ内の見出しに対しては、コード側で bold とフォントサイズを設定します。フォント種類・色はプレースホルダのデフォルトを継承します。
| レベル | フォントサイズ | 太字 | 配置先 |
|---|---|---|---|
| h2 | 24pt | bold | 本文PH（2番目以降の h2） |
| h3 | 20pt | bold | 本文PH |
| h4 | 18pt | bold | 本文PH |
| h5 | 16pt | bold | 本文PH |
| h6 | 14pt | bold | 本文PH |
テキスト高さの推定
本文プレースホルダ内にテキストと後続要素（テーブル、コードブロック、画像）が混在する場合、テキスト部分の描画高さを推定して後続要素の配置位置を計算します。
- デフォルトフォントサイズ: 18pt（段落・リスト）
- 行高さ倍率: 2.0（段落間スペース・バレット余白を含む）
- 見出しは
headingFontSize()の値を使用
既知の制約と今後の検討
本文プレースホルダ内見出しのテンプレートスタイル委任（#131 Phase 2）
本文プレースホルダ内の見出し（h3〜h6、および2番目以降の h2）については、現状コード側で bold/フォントサイズを設定している。将来的にプレースホルダのデフォルトに委任することを検討中。PowerPoint には見出しレベルの概念がないため、段落レベルのデフォルトスタイルに任せた場合のフォント種類・色の継承を要検証。
h2〜h6 のフォント種類・色の継承
コード側がフォントサイズのみを設定し、フォント種類・色はプレースホルダのデフォルトを継承させる設計。python-pptx での挙動（明示的にサイズを指定した場合にフォント種類・色が継承されるか）は要検証。
部分未マッピング要素の扱い
一部の要素だけマッピングできた場合、未マッピング要素は出力されない。将来的に、未マッピング要素を Blank エリアに配置するなどの救済策を検討する余地がある。
関連ドキュメント
- Markdown 記法仕様 — サポートされる Markdown 記法の詳細
- テンプレート PPTX 準備ガイド — テンプレートの作成方法
- #131 — テンプレートプレースホルダ尊重方針の議論