md-pptx Markdown記法仕様

設計方針

Marp互換をベースとし、PPTX固有の機能は独自拡張で対応する
非エンジニアにも書きやすいシンプルな記法を目指す
Marpで書いたMarkdownを最小限の修正でmd-pptxに移行できることを目標とする

Marp互換性の範囲

区分	記法	対応状況
互換	`---` スライド区切り	Marpと同一
互換	YAML Front matter	Marpと同一（キーは異なる）
互換	HTMLコメントディレクティブ	Marpと同一
互換	`_` プレフィックスのスポットディレクティブ	Marpと同一
互換	画像リサイズ `![w:200](img.png)`	Marpと同一
互換	プレゼンターノート（HTMLコメント）	Marpと同一
互換	テーブル記法	Markdown標準
独自	`template` フロントマター	md-pptx固有
独自	`layout` ディレクティブ	md-pptx固有
非対応	`theme` / `style`	PPTXテンプレートで代替
非対応	`bg` 背景画像構文	PPTXテンプレートの背景を使用
非対応	フラグメントリスト	PPTX出力では不要
非対応	トランジション	スコープ外
非対応	フィッティングヘッダー	PPTXプレースホルダのサイズに依存

フロントマター

Markdownファイルの先頭に YAML 形式で記述する。グローバル設定を定義する。

yaml

---
template: ./templates/company.pptx
layout: Title Slide
headingDivider: 2
---

グローバルディレクティブ一覧

キー	型	説明
`template`	string	テンプレートPPTXファイルのパス（省略時は空のプレゼンテーションを生成）
`layout`	string	デフォルトのスライドレイアウト名
`headingDivider`	number \| number[]	指定した見出しレベルで自動的にスライドを分割（Marp互換）
`author`	string	作成者（PPTXメタデータに設定）
`title`	string	プレゼンテーションのタイトル（PPTXメタデータに設定）

template が指定されていない場合は、Blankレイアウトのみの空のプレゼンテーションを生成する
layout はフロントマターで指定した場合、全スライドのデフォルトレイアウトとなる

スライド区切り

水平罫線 --- でスライドを分割する（Marp互換）。

markdown

# スライド1のタイトル

スライド1の本文

---

# スライド2のタイトル

スライド2の本文

headingDivider による自動分割

headingDivider ディレクティブを指定すると、指定レベルの見出しで自動的にスライドが分割される。

markdown

---
template: ./template.pptx
headingDivider: 2
---

# セクション1

## スライド1
本文

## スライド2
本文

# セクション2

## スライド3
本文

上記は ## の前で自動的にスライドが分割され、4枚のスライドになる。

ディレクティブ

記述方法

HTMLコメント形式で記述する（Marp互換）。

markdown

<!-- layout: Title Slide -->
<!-- _layout: Section Header -->

ローカルディレクティブ

定義したスライド以降のすべてのスライドに適用される。

キー	型	説明
`layout`	string	スライドレイアウト名（テンプレートPPTXのレイアウト名に対応）
`paginate`	boolean	ページ番号の表示（将来実装）
`header`	string	ヘッダーテキスト（将来実装）
`footer`	string	フッターテキスト（将来実装）

スポットディレクティブ

ディレクティブ名の先頭に _ を付けると、そのスライドだけに適用される（Marp互換）。

markdown

<!-- layout: Two Content -->

## 通常スライド（Two Content レイアウト）

本文

---

<!-- _layout: Title Slide -->

# タイトルだけ別レイアウト

---

## このスライドはTwo Contentに戻る

本文

プレースホルダマッピング

Markdownの構造をPPTXプレースホルダに自動的にマッピングする。

デフォルトマッピング

Markdown要素	PPTXプレースホルダ
`# 見出し` (`h1`)	title プレースホルダ（type=TITLE, idx=0）
`## 見出し` (`h2`)	title プレースホルダ（type=TITLE, idx=0）
本文テキスト（段落、リスト、テーブル等）	body プレースホルダ（type=BODY, idx=1）
`![](image.png)`	picture プレースホルダ（type=PICTURE）があれば使用

最初に見つかった見出し（# または ##）が title プレースホルダにマッピングされる
見出し以降のテキスト要素は body プレースホルダにマッピングされる
レイアウトに対応するプレースホルダが存在しない場合は、Blankレイアウトにフォールバックし自前で配置する

テキストの書式

本文テキスト内では以下のMarkdown書式がサポートされる。

Markdown	PPTX上の表現
`太字`	太字（Bold）
`斜体`	斜体（Italic）
`コード`	等幅フォント（Courier New） + カラー
`~~取り消し線~~`	取り消し線
`[リンク](url)`	ハイパーリンク

箇条書き・番号付きリスト

markdown

- 項目1
- 項目2
  - ネスト項目
    - さらにネスト

1. 番号付き項目1
2. 番号付き項目2

ネストはPPTXのインデントレベルにマッピングされる（最大9レベル）。

画像

基本構文

markdown

![代替テキスト](./images/photo.png)

サイズ指定（Marp互換）

alt テキスト内にサイズを指定できる。

markdown

![w:400](./images/photo.png)
![h:300](./images/photo.png)
![w:400 h:300](./images/photo.png)
![width:400px height:300px](./images/photo.png)

w / width: 幅の指定
h / height: 高さの指定
単位を省略した場合はピクセルとして扱う
片方のみ指定した場合はアスペクト比を維持してスケーリングする

画像の配置

picture プレースホルダが存在するレイアウトの場合、画像はそのプレースホルダ内に配置される。プレースホルダが存在しない場合は、スライド上に直接配置される。

テーブル

Markdownのテーブル記法でPPTXテーブルを生成できる。

基本構文

markdown

| 項目 | 値   | 備考       |
|------|------|------------|
| A    | 100  | サンプル   |
| B    | 200  | テスト     |

仕様

1行目はヘッダー行として太字で表示される
2行目の --- は区切り行（ヘッダーとボディの境界）
3行目以降がデータ行
セル内ではインライン書式（**太字**、*斜体*、`コード`、[リンク](url)）が使用可能
テーブルは body プレースホルダの位置を基準にシェイプとして配置される

表示仕様

項目	値
ヘッダー行	太字
マッピング先	body プレースホルダ

コードブロック

フェンスドコードブロック（```）でコードスニペットを記述できる。PPTX上では等幅フォント（Courier New）で表示される。

基本構文

markdown

```typescript
function hello(name: string) {
  console.log(`Hello, ${name}!`);
}
```

言語指定

開始フェンスの後に言語名を記述できる。現時点ではシンタックスハイライトには非対応だが、言語情報は保持される。

markdown

```python
def greet(name):
    print(f"Hello, {name}!")
```

表示仕様

項目	値
フォント	Courier New（等幅）
フォントサイズ	10pt
シンタックスハイライト	非対応（将来対応予定）
マッピング先	body プレースホルダ

プレゼンターノート

HTMLコメントのうち、ディレクティブとして解釈されないものはプレゼンターノートとして扱われる（Marp互換）。

markdown

# スライドタイトル

本文テキスト

<!-- ここに話すポイントを書く -->
<!-- layout: は ディレクティブとして解釈される -->
<!-- これはプレゼンターノート -->

ディレクティブとの判別ルール:

 の形式で、key が既知のディレクティブ名に一致する場合 → ディレクティブ
それ以外 → プレゼンターノート

完全な例

markdown

---
template: ./templates/company.pptx
title: 2024年度 事業報告
author: 山田太郎
---

<!-- _layout: Title Slide -->

# 2024年度 事業報告

株式会社サンプル

<!-- 挨拶から始める。時間は30分。 -->

---

<!-- layout: Title and Content -->

## 売上サマリー

- 売上高: **120億円**（前年比 +15%）
- 営業利益: **18億円**（前年比 +22%）
- 新規顧客数: *350社*

<!-- 売上高の内訳を聞かれたらP5を参照 -->

---

## 主要施策の成果

1. 新製品Aのローンチ
   - 発売3ヶ月で目標の120%達成
2. 海外展開の加速
   - アジア3カ国に新規進出
3. DX推進
   - 社内業務の~~手作業~~自動化率 80%達成

---

<!-- _layout: Two Content -->

## 今後の展望

- 2025年度 売上目標: **150億円**
- 重点投資領域:
  - AI活用
  - サステナビリティ

![w:400](./images/roadmap.png)

---

<!-- _layout: Title Slide -->

# ご清聴ありがとうございました

お問い合わせ: [info@example.com](mailto:info@example.com)

md-pptx Markdown記法仕様 ​

設計方針 ​

Marp互換性の範囲 ​

フロントマター ​

グローバルディレクティブ一覧 ​

スライド区切り ​

headingDivider による自動分割 ​

ディレクティブ ​

記述方法 ​

ローカルディレクティブ ​

スポットディレクティブ ​

プレースホルダマッピング ​

デフォルトマッピング ​

テキストの書式 ​

箇条書き・番号付きリスト ​

画像 ​

基本構文 ​

サイズ指定（Marp互換） ​

画像の配置 ​

テーブル ​

基本構文 ​

仕様 ​

表示仕様 ​

コードブロック ​

基本構文 ​

言語指定 ​

表示仕様 ​

プレゼンターノート ​

完全な例 ​

md-pptx Markdown記法仕様

設計方針

Marp互換性の範囲

フロントマター

グローバルディレクティブ一覧

スライド区切り

headingDivider による自動分割

ディレクティブ

記述方法

ローカルディレクティブ

スポットディレクティブ

プレースホルダマッピング

デフォルトマッピング

テキストの書式

箇条書き・番号付きリスト

画像

基本構文

サイズ指定（Marp互換）

画像の配置

テーブル

基本構文

仕様

表示仕様

コードブロック

基本構文

言語指定

表示仕様

プレゼンターノート

完全な例