pptx

PowerPoint デッキ

python-pptx と PptxGenJS はすでにご存じでしょう。このスキルでは、HTML スライドをネイティブで編集可能な PowerPoint オブジェクトに変換するコンバーター、テンプレートを確実に扱うためのスクリプト、そしてデッキの妥当性と見栄えを確認するためのチェック機能を追加します。

スクリプトの実行

<skill> はこのファイルが含まれるディレクトリです。バンドルされたスクリプトは、ユーザーの作業ディレクトリから絶対パスで実行してください。そうすることで、スクリプト内のファイルへの相対パスが正しく機能します。

uv run <skill>/scripts/thumbnail.py deck.pptx

作成した Python は、依存関係を宣言して実行してください。uv run --with python-pptx script.py を使うか、PEP 723 ヘッダーを追加します。Node スクリプトは NODE_PATH=<skill>/node_modules node build.js で実行します。<skill>/node_modules がない場合は、<skill> 内で一度 npm install を実行してください。レンダリングには LibreOffice（soffice）と poppler（pdftoppm）が必要です。

ワークフローの選択

タスク	ワークフロー
デッキのテキストを読む	uv run --with 'markitdown[pptx]' python -m markitdown deck.pptx
新しいデッキを作成する（テンプレートなし）	以下の html2pptx を使用します。まず html2pptx.md と design.md を読んでください。
テンプレートから新しいデッキを作成する	以下のテンプレートワークフローを使用します
既存のデッキを変更する	テキストと図形には python-pptx を使用します。python-pptx で扱えないものにはスライド XML（ooxml.md）を使用します。
発表者ノート	scripts/notes.py

markitdown はスライドを 1 から番号付けし（``）、このディレクトリの各スクリプトは 0 から数えます。既存のデッキの見た目を踏襲するには、展開したファイルから ppt/theme/theme1.xml（<a:clrScheme>、<a:fontScheme>）を読み取り、サムネイル一覧を確認してください。

新しいデッキ：html2pptx

1. デザインシステム（design.md）を決めます。配色、文字のスケール、グリッドを定め、コードを書く前に 2 文で説明してください。
2. html2pptx.md のルールに従って、スライドごとに HTML ファイルを 1 つ作成します。グラフと表の領域には class="placeholder" を指定してください。
3. 各スライドに対して html2pptx() を呼び出し、プレースホルダーに PptxGenJS でグラフと表を追加して、pptx.writeFile({ fileName }) を呼び出すビルドスクリプトを作成します。html2pptx はスライド上の問題をすべて一度に報告します。すべて修正してから再実行してください。
4. 出力を確認します（以下を参照）。

テンプレートから新しいデッキを作成する

1. テンプレートを確認します。 markitdown でテキストを抽出し、uv run <skill>/scripts/thumbnail.py template.pptx grid でサムネイル一覧を作成します。グリッド画像を確認してください。

2. レイアウトを一覧にします。 各スライドを 0 から始まるインデックスで列挙し、用途を記載します。例：「12：2 列、各列に見出しと箇条書き」。

3. コンテンツをレイアウトに割り当てます。 まず各スライドのコンテンツ項目数を数え、その数と一致するスロット数のレイアウトを選びます。

   • 項目が 2 つなら 2 列、3 つなら 3 列のレイアウトを使用します
   • 画像がある場合に限り、画像レイアウトを使用します
   • 出典付きの実際の引用がある場合に限り、引用レイアウトを使用します
   • 項目が 4 つ以上ある場合は、複数のスライドに分けるか、リストにします

   プレースホルダーを空のままにしたり、埋めるためにダミーの内容を作ったりしないでください。

4. スライドを組み立てます。 複製には、グラフ、埋め込みワークブック、ノート、リンクがすべて含まれます。

   uv run <skill>/scripts/rearrange.py template.pptx working.pptx 0,12,12,31,40
   

5. テキストを一覧にします。 inventory.json をすべて読み取ります。

   uv run <skill>/scripts/inventory.py working.pptx inventory.json
   

6. 置換内容を記述し（形式は以下を参照）、適用します。

   uv run <skill>/scripts/replace.py working.pptx replacements.json output.pptx
   

7. 出力を確認します（以下を参照）。

インベントリと置換

inventory.json は slide-N を shape-N に対応付けます。どちらも 0 始まりです。図形は上から下、次に左から右の順に並び、スライド番号は省略されています。各図形には、インチ単位の left、top、width、height と paragraphs が含まれます。また、次の情報も含まれます。

• placeholder_type（TITLE、CENTER_TITLE、SUBTITLE、BODY、OBJECT、…）。プレースホルダーの場合のみ
• レイアウトで設定されている場合の default_font_size
• 検出された場合の overflow、overlap、warnings

段落には、デフォルトと異なるプロパティのみが記載されます。

置換ファイルも同じ形式で、各図形に入力する paragraphs を指定します。

{
  "slide-0": {
    "shape-0": {"paragraphs": [{"text": "Revenue grew 18%", "bold": true}]},
    "shape-1": {"paragraphs": [
      {"text": "Renewals drove two thirds of growth"},
      {"text": "Churn fell to 4%", "bullet": true, "level": 0}
    ]}
  }
}

• 段落フィールド：
  • text、bold、italic、underline
  • font_size、font_name
  • color（"C0392B"）または theme_color（"ACCENT_1"）
  • alignment（LEFT、CENTER、RIGHT、JUSTIFY）
  • space_before、space_after、line_spacing（ポイント単位）
  • level を含む bullet
• テンプレートのスタイルが維持されるよう、インベントリにスロットのプロパティが示されている場合は、そのプロパティを引き継いでください。
• 箇条書き記号は入力しないでください。箇条書きの段落は自動的に左揃えになります。
• 記載された各スライドでは、すべてのテキスト図形がクリアされてから入力されます。 ファイルに含まれない図形は空になり、テンプレートに残っていたテキストが削除されます。記載されていないスライドには変更が加えられません。
• キーが存在しない場合（「Shape 'shape-9' not found on 'slide-0'. Available shapes: …」）、または新しいテキストが元のテキストよりも大きくボックスからはみ出す場合（「Text overflow worsened: slide-0/shape-2: …」）、replace.py は何も保存しません。テキストを短くするか、より広いレイアウトを選んでください。

スライド XML の編集

最初に ooxml.md を読んでください。その後、展開して編集し、変更のたびに検証してから再パッケージ化します。

uv run <skill>/ooxml/scripts/unpack.py deck.pptx unpacked
uv run <skill>/ooxml/scripts/validate.py unpacked --original deck.pptx
uv run <skill>/ooxml/scripts/pack.py unpacked edited.pptx

発表者ノート

uv run <skill>/scripts/notes.py deck.pptx                    # print {"slide-0": "…", …}
uv run <skill>/scripts/notes.py deck.pptx notes.json -o out.pptx

JSON ではスライドキーとプレーンテキストを対応付け、1 行につき 1 段落を指定します。空文字列を指定するとスライドのノートがクリアされ、記載されていないスライドのノートはそのまま保持されます。html2pptx でビルドする場合は、代わりに slide.addNotes('…') を使用してください。

出力の確認

検証に合格し、すべてのスライドを確認したら、デッキは完成です。

1. 検証します。 新しいデッキの場合は、uv run <skill>/ooxml/scripts/validate.py deck.pptx を実行します。編集したデッキ、またはテンプレートから作成したデッキの場合は、--original template.pptx を追加して、新たに発生した問題のみを報告させます。報告された問題をすべて修正してください。

   複製したスライドの場合、validate.py はテンプレートに元からあったスキーマエラーも報告します。対処する前に、元のスライドと比較してください。

2. 目視で確認します。 uv run <skill>/ooxml/scripts/render.py deck.pptx pages を実行し、すべての画像を確認します。次の点に注意してください。

   • テキストが切れている、重なっている、または端に寄りすぎている
   • コントラストが弱い
   • テンプレートのテキストが残っている、またはプレースホルダーが空になっている
   • グリッドから外れているもの 　 thumbnail.py deck.pptx grid --outline-placeholders を実行すると、すべてのテキストボックスの輪郭が表示された概要を確認できます。

3. 両方に問題がなくなるまで、修正と確認を繰り返してください。

気づかないうちに失敗する落とし穴

• PptxGenJS の色には # を付けません。'#C0392B' を指定するとファイルが破損します。
• ブラウザーで収まるテキストでも、フォントが置き換えられると PowerPoint であふれることがあります。design.md のフォントポリシーに従ってください。
• スライドの XML を手作業でコピーして複製すると、グラフが失われ、スライド間でノートが共有されます。rearrange.py を使用してください。
• markitdown の出力を除き、スライドのインデックスはすべて 0 始まりです。