Markdown 執筆ガイド
SlideCraft は入力された Markdown を「1 スライド分ずつ」のブロックに区切り、各ブロックをタイトル・本文・図などの構造に解釈して、テンプレートの色・フォント・レイアウトに流し込みます。このページでは、スライドを組み立てるための Markdown 記法を網羅的に説明します。
配置や装飾はテンプレートとエンジンにまかせる分業なので、フォントサイズを手で縮めたり座標を細かく指定したりせずに、整ったスライドが作れます。図（ダイアグラム）の記法だけは分量が多いため、図 に分けています。
前提
まだアプリを入れていない場合は インストール を先にどうぞ。SlideCraft の考え方（書く → 見る → 出す）は各ページ冒頭でも触れています。
スライド区切り ---
---（水平線）だけの行が 1 枚のスライドの境界です。区切りごとに 1 枚のスライドが生成されます。
# 最初のスライド
- ポイント1
- ポイント2
---
# 次のスライド
本文テキスト。上の例は 2 枚のスライドになります。区切りは行頭が --- の行そのものです。GFM 表の区切り行（|---|---|）はセルの縦棒を伴うので、スライド区切りと混同されません。
TIP
先頭に空行があっても大丈夫です。区切りが残す先頭の空行はパーサが読み飛ばします。
タイトル・サブタイトル・本文
1 枚のスライドの中身は、見出しレベルと行の種類で役割が決まります。
| 記法 | 役割 |
|---|---|
# 見出し | スライドのタイトル |
## 見出し または > 引用 | サブタイトル |
- / * の箇条書き、段落 | 本文 |
1. / 1) の番号付きリスト | 本文（自動番号。保存時は 1. 2. … の連番に正規化） |
### 見出し | グループ（カラム/カード/ステップ）内の小見出し |
**太字** / *斜体* | インライン装飾 |
# 2026年 事業計画
> 第2四半期レビュー
- 売上は前年比 **+12%**
- 新規顧客は *120 社*いくつか挙動を押さえておくと安全です。
#は最初の 1 つだけがタイトルになります。2 つめ以降の#行は本文として扱われます。- サブタイトルは
##でも>（引用）でも指定できます。ただし>はタイトルの直後・本文が始まる前に置いたときだけサブタイトルになります。本文が始まったあとの>は、引用マーカーを外した普通の本文行になります。 - サブタイトルも 1 つだけ拾われます。
よくある取り違え
本文の途中に > の行を入れると、引用ブロックではなく「> を外した本文」として表示されます。SlideCraft の Markdown は汎用の Markdown ビューアではなく、スライド構造への変換器である点に注意してください。
メタ情報 Category: / Date: / Footer:
タイトルスライドでは、Category: / Date: / Footer: で始まる行がメタ情報として扱われ、テンプレートの対応する枠（分類・日付・フッタ）に流し込まれます。
# 2026年 事業計画
> 第2四半期レビュー
Category: 経営会議
Date: 2026-07-07
Footer: 社外秘覚えておくべき点：
- キーは
Category/Date/Footerの 3 つだけです（大文字小文字は問いません）。この 3 つのどれかがあると、そのスライドはタイトル系スライドとして扱われます（メタ枠を持つレイアウトが選ばれやすくなります）。 Meta:やSummary:のような別のキーはメタ扱いされず、本文行になります。特別扱いされるのは上記 3 つだけです。- レイアウトを自動選択にまかせず特定のレイアウトを使いたいときは、ブロックの先頭行に
<!-- slide: レイアウト名 -->を書きます。通常は省略して自動選択（auto）で構いません。
<!-- slide: title-centered -->
# 表紙タイトル結論帯 Takeaway: / 出典行 Source:
コンテンツスライドには、本文とは別に次の 2 種類のフィールド行（1 行で書く キー: 値）を書けます。テンプレートに専用の枠があれば、その枠を持つレイアウトが自動で選ばれ、そこに流し込まれます。
Takeaway:— そのスライドの結論を 1 行で。「1 スライド 1 メッセージ」を守るため、コンテンツスライドには原則 1 行書きます。本文は結論の根拠に徹します。コールアウト枠（例: Midnight のContent.1Body.Single+1Callout）に入ります。Source:— データの出典。数値・表・グラフを見せるスライドには必ず書きます。出典枠（例: Midnight のContent.1Body.Single+1Source、表ならTable.1Table.Single+1Source／公文書テンプレの出典枠）に入ります。
# 地域別人口
| 地域 | 人口 |
|---|---|
| 東京 | 1400万 |
Takeaway: 人口は首都圏へ一極集中が続く
Source: 総務省 2025覚えておくべき点：
- キーは
Takeaway/Sourceの 2 つです（下のKickerも同じ仕組みです。大文字小文字は問いません）。スライド内のどの位置に書いても構いません（書き出し時はスライド本文の後ろにまとまります）。 - 同じキーを複数行書くと、それぞれが 1 段落として枠に入ります（例: 出典が 2 つ）。
Category:などのメタ情報と違い、フィールド行があってもタイトル系スライドにはなりません。- 列区切り（
<!-- col -->/<!-- card -->など）のあるスライドでも使えます（スライド全体の行として扱い、最後の列には含めません）。 - コードフェンス内の
Source:は普通のコードのままです。 - テンプレート（またはピン留めしたレイアウト）に該当の枠が無い場合、その行は出力されません。MCP の
get_deck_issuesには「Takeaway:行の置き場（専用枠）がこのレイアウトにありません」と警告が出ます（アプリ画面の診断表示への反映は #419 で対応予定）。本文に書き直すか、枠のあるテンプレートを使ってください。
カテゴリ行 Kicker:
Kicker: は、コンテンツスライドのタイトルの上に置く小さなカテゴリ行（例: SECTION 02 · コスト分析）です。Takeaway: / Source: と同じフィールド行で、テンプレートに名前が Kicker / Eyebrow で始まる枠があれば、その枠を持つレイアウトが自動で選ばれ、そこに入ります。
# コスト構造の内訳
- 人件費が 6 割
- 外注費が増加
Kicker: SECTION 02 · コスト分析覚えておくべき点：
- Midnight Executive（既定テンプレート）には Kicker 枠付きのコンテンツレイアウト
Content.1Body.Single+1Kickerがあります。Kicker:行を書くとこのレイアウトが自動で選ばれ、タイトルの上に描画されます。その他の同梱テンプレート（技術報告・ビジュアルデッキ・配布資料）にはまだ枠が無く、その場合は出力されず、get_deck_issuesに「Kicker:行の置き場（専用枠）がこのレイアウトにありません」と警告が出ます。AI 向けの案内（get_authoring_guide）には、枠のあるテンプレートのときだけKicker:が載ります。 - タイトルスライドの分類行は従来どおり
Category:です。Kicker:を書いてもタイトル系スライドにはならず、Category:の意味も変わりません。 - どの章のスライドかを示したいだけなら、章扉の
<!-- section -->（後述）を使ってください。フッタ枠のあるテンプレートでは、章扉以降の各スライドのフッタに所属章の名前が自動で入ります。Kicker:は、章名とは別のラベルを個々のスライドに付けたいときに使います。
GFM 表
標準的な GFM（GitHub Flavored Markdown）の表は、画像ではなくネイティブな PPTX 表（PowerPoint で編集可能なセル）になります。ヘッダ行つきの表として本文領域に入ります。
# 比較表
| 項目 | 旧プラン | 新プラン |
|------|---------|---------|
| 料金 | ¥1,000 | ¥800 |
| 容量 | 10 GB | 30 GB |- 表は
| … |の行と、直後の区切り行（|---|---|）の組で認識されます。 - 本文中のどこにあっても最初の表 1 つがネイティブ表になります。
- 表は画像化されないので、出力後の PPTX 上でそのままセルを編集できます。
画像 
画像は行に単独で  を書くと埋め込み画像になります。
データ URI のみ
埋め込み画像になるのは データ URI（data:image/...;base64,...）だけです。リモート URL・ローカルパス・javascript: などの src は、安全のため画像化されず、その行はそのまま本文テキストとして扱われます。データ URI に変換してから貼り込んでください。
# ロゴ
画像はプレビューにも HTML 出力にも自動で入り、PPTX ではデコードされてメディアとして貼り込まれます。1 枚のスライドで画像として拾われるのは最初の 1 つだけで、それ以降の画像行は本文テキストに落ちます。
位置・サイズ・切り抜きの属性 {...}
画像行の末尾に {...} を付けると、位置・サイズ・切り抜き・レイヤーを細かく指定できます。属性はカンマ区切りの キー=値 です。
{x=0,y=0,w=13.33,h=7.5,fit=cover,behind=1}| キー | 意味 | 値 |
|---|---|---|
x y | 左上の位置（インチ） | 数値 |
w h | 幅・高さ（インチ） | 数値 |
fit | 枠への収め方 | cover（切り抜いて埋める）/ contain（全体を収める） |
ar | 元画像のアスペクト比（w/h） | 正の数値 |
behind | 最背面レイヤーに敷く | 1 |
覚えておく点：
- 座標系は 13.33 × 7.5 インチのスライド上のインチです（
x=0,y=0が左上、w=13.33,h=7.5でスライド全面）。 xywhは 4 つそろって初めて位置指定として効きます。一部だけ書いても無視され、画像は割り当てられた枠を埋めます。- 属性を省略した
は、割り当てられた本文枠を埋める既定サイズになります。 - 視覚エディタ上でドラッグ移動・リサイズでき、その結果がこの
{...}属性として Markdown に保存されます（往復可能）。手で書くより、まず配置してから書き出す使い方が楽です。 behind=1は画像を最背面に敷きます。背景写真や地紋の上に本文を載せる用途に向きます。![alt]の alt 文字列は画像の直下に 1 行のキャプション（説明・出典）として描かれ、PPTX では画像の代替テキストにもなります。キャプションが要らないときはと alt を空にします。最背面（behind=1）の画像はキャプションを描かず、代替テキストだけを書きます。
カラム分割スライドでも背景画像は使える
<!-- col --> などで分割したスライドでも、単独の画像行（特に behind=1 の背景）は各カラムの本文に取り込まれず、スライド全体の背景として扱われます。
多カラム / KPI / ステップ / カード / 比較
1 枚のスライドの本文を複数の領域に分けたいときは、区切りコメントを使います。# タイトル の後に同じ種類の区切りコメントを並べ、その間に各領域の内容を書きます。
| 区切りコメント | 用途 |
|---|---|
<!-- col --> | 横並びの複数カラム |
<!-- kpi --> | KPI（大きな数字）タイル |
<!-- step --> | プロセス／手順ステップ |
<!-- card --> | カード |
<!-- compare --> | 2 案の対比（A 案 vs B 案） |
<!-- before --> / <!-- after --> | 変化の前後（As-is → To-be）。矢印と Before/After ラベル付き |
# 3本柱
<!-- col -->
### 品質
- 不良率を半減
<!-- col -->
### 速度
- リードタイム短縮
<!-- col -->
### コスト
- 原価 10% 削減使い方のポイント：
- 区切りコメントはそれだけの行（
<!-- col -->のように前後に本文を書かない）にします。 - 最初の区切りコメントより前に書いた内容は、タイトル／サブタイトル以外は各領域には入りません。タイトル（
#）とサブタイトル（>）はスライド全体の見出しになり、各領域の中身は区切りのあいだに書きます。 - 各領域では
### 小見出しが領域のヘッダになり、その下に箇条書きや段落を書きます。 col（素のカラム）以外のkpi/step/card/compare/before・afterは、対応するレイアウト（KPI タイル・プロセス・カード・比較）を選ぶヒントになります。colはヒントを持たない素の横並びです。
2 案の比較 <!-- compare -->
A 案と B 案のように対等な 2 つを並べて比べるときは <!-- compare --> を使います。テンプレートの比較レイアウト（例: Compare.2Option.Versus、報告書テンプレートの 12_課題と対策）が自動で選ばれ、各領域の ### 見出し が案の名前、その下が中身になります。
# A 案と B 案
<!-- compare -->
### A 案：内製
- 初期費用が低い
- 立ち上げに半年
<!-- compare -->
### B 案：外注
- 初期費用が高い
- 1 か月で稼働- 比較レイアウトは 2 領域用です。3 つ以上を並べると通常の多カラムとして配置されます（3 案以上の比較は
<!-- col -->か表で書くのが向いています）。 - テンプレートに比較レイアウトが無い場合も、通常の多カラムとして表示されます。
変化の前後 <!-- before --> / <!-- after -->
改善提案や移行説明のように左（現状）から右（あるべき姿）への変化を示すときは、<!-- before --> と <!-- after --> を 1 つずつ使います。レイアウトは比較と同じものを使い、その上に左右の間の矢印と各領域の上の Before / After ラベルが自動で付きます。
# 承認フローの見直し
<!-- before -->
### 現状
- 紙の申請書を回覧
- 承認まで平均 5 日
<!-- after -->
### 見直し後
- ワークフローで電子承認
- 承認まで平均 1 日- 意味は位置で決まります。1 つ目の領域が Before、2 つ目が After です。順番を入れ替えて書いても、左が Before として描かれます（書き出し時のマーカーも描かれたとおり
before→afterの順に揃います）。 - 矢印と Before/After ラベルの色はテンプレートのテーマ色（アクセント色）です。テンプレートのレイアウト自体に矢印が描かれている場合（報告書テンプレートの
12_課題と対策など）は、その矢印をそのまま使い、矢印を重ねて描きません。 - 2 つ目より後に領域を足すと、それらも After として扱われます。前後の 2 面構造なので、領域は 2 つにしてください。
見出しにアイコンを付ける
カード／ステップ／KPI の領域の ### 見出し は、先頭に :アイコン名: を書くと見出しの左に組み込みアイコン（図のノードと同じもの）が付きます。:server: 自体は印字されません。
<!-- card -->
### :server: 可用性
- 冗長構成- 使えるアイコン名：
routerswitchserverdatabasecloudfirewallclientinternetload_balancerwireless_apstorageprinterphonevpnmonitor（db→database のような別名・大文字小文字の違いも受け付けます）。 - 知らない名前（例:
:nosuch:）はアイコンにならず、そのまま文字として表示されます（打ち間違いで内容が消えることはありません）。 - 見出しの先頭に装飾なしで書いたときだけアイコンになります（
**:server:**のように太字などで囲むと文字のまま）。 - グループ用レイアウト（カード・プロセス等）に載ったときに描画されます。そうでないレイアウトでは文字のまま残ります。
現在のステップを強調する
プロセス帯で「今ここ」を示すには、そのステップの区切りを <!-- step * --> にします。そのステップの見出しが太字になり、列が細い枠で囲まれます。
<!-- step -->
### 要件
<!-- step * -->
### 設計
<!-- step -->
### 実装*を付けられるのはstepだけです（card/kpiには付きません）。
領域に図を置く
各領域には本文の代わりに図を置くこともできます。領域の中に ```diagram または ```mermaid フェンスを書くと、その領域が図になり、他のカラムと横に並びます。
# 構成と指標
<!-- col -->
### 構成
```diagram
type: pie
nodes:
- { id: a, label: 国内, value: 60 }
- { id: b, label: 海外, value: 40 }
```
<!-- col -->
### 指標
- 稼働率 98%
- 月次成長 +12%図の記法そのものは 図 を参照してください。
スピーカーノート <!-- note -->
<!-- note --> を単独行で置くと、そこからスライド末尾（次の ---）までがそのスライドのスピーカーノートになります。ノート本文は素の Markdown（複数行・箇条書き・**強調** 可）で、スライド面には表示されません。
# 提案の骨子
- 結論だけを載せる
<!-- note -->
ここから発表者ノート。口頭で補足する背景・数字の出典・想定問答などを
複数行で書けます。
- 箇条書きも使えます覚えておく点：
- マーカーはそのスライドの一番最後に置きます。マーカー以降はすべてノートとして扱われるためです。
- マーカーだけが不可視で、ノート本文は普通の Markdown 段落です。GitHub などで Markdown をそのまま見ても自然に読めます。
- PPTX 出力では PowerPoint のネイティブなスピーカーノート（ノートペイン）になります。
- HTML 出力では既定で非表示、
nキーでノートパネルの表示を切り替えられます（編集と出力）。 - あふれ分割（自動分割）が起きた場合、ノートは先頭のスライドだけに残ります（複製されません）。
<!-- note: メモ -->のように本文をマーカー内に書いた形はノートになりません（従来どおり破棄されるコメントです）。ノート本文はマーカーの次の行から書いてください。
「スライドは疎に・詳細はノートへ」のブリーフィング型の書き方に向いています。本文の収容量（バジェット）を超えそうな説明は、ノートへ逃がすときれいに収まります。
章と目次 <!-- section --> / <!-- toc -->
章扉は自動生成されず、著者が書く普通のスライドです。章にしたいスライドのブロックに <!-- section --> を単独行で置くと、そのスライドが章境界として宣言されます。章名は # 見出しのままなので、Markdown をそのまま見ても章構造が読めます。
<!-- toc --> だけを書いたスライドブロックは目次スライドになります。目次の中身（章番号＋章名）は、section タグ付きスライドから常に自動導出されます。
<!-- toc -->
---
<!-- section -->
# 現状分析
> 章の補足説明（任意）
---
# 現状分析の詳細スライド…覚えておく点：
- 章番号は section タグ付きスライドの出現順で自動採番されます。
- 目次は手で編集できません（Markdown へは
<!-- toc -->の 1 行だけが書き戻されます）。章扉のタイトルを変えると、目次は次の表示・出力で自動的に追随します — 目次と本文の乖離が構造的に起きない仕組みです。 <!-- slide: レイアウト名 -->のピンとは直交です。章扉も自動選択（Section 系レイアウトに解決されやすい）またはピン固定のどちらでも使えます。- タグを書かない Markdown の出力は従来と変わりません。
コードフェンス
``` で囲んだフェンスブロックは、フェンスの言語名で扱いが変わります。
| フェンス | 扱い |
|---|---|
```diagram | DiagramSpec（YAML/JSON）でネイティブ図を描く → 図 |
```mermaid | Mermaid 記法。変換できるものはネイティブ図に、それ以外は Mermaid 画像フォールバック |
その他（```yaml / ```python / 言語なしの ``` など） | 等幅フォントのコード／ログとして表示 |
# 設定例
```yaml
server:
port: 8080
workers: 4
```図に使わないフェンス（yaml / python / bash / log / 言語指定なし、など）は、内容が等幅フォントのコードブロックとしてそのままスライドに載ります。言語名は表示上のヒントとして保持されます。
図に変換できない Mermaid
Mermaid の gitGraph / sankey / C4 などは、ネイティブ図に変換できず PPTX にも出力できません。既定では出力時に拒否され、無言で消えることはありません。対応する図（図 の 12 種、または変換可能な Mermaid）に置き換えてください。詳しくは FAQ を参照してください。
本文があふれるとき
本文がスライドに収まらない場合、エンジンは決定論的にあふれを分割し、内容を複数スライドに割ります。フォントを無理に縮めて 1 枚に押し込むことはしません。長い箇条書きは、内容を要約するか、GFM 表への整理などで見やすくできます。要約は内蔵 AI にも手伝わせられます（AI設定）。