Markdown 執筆ガイド
SlideCraft は入力された Markdown を「1 スライド分ずつ」のブロックに区切り、各ブロックをタイトル・本文・図などの構造に解釈して、テンプレートの色・フォント・レイアウトに流し込みます。このページでは、スライドを組み立てるための Markdown 記法を網羅的に説明します。
配置や装飾はテンプレートとエンジンにまかせる分業なので、フォントサイズを手で縮めたり座標を細かく指定したりせずに、整ったスライドが作れます。図（ダイアグラム）の記法だけは分量が多いため、図 に分けています。
前提
まだアプリを入れていない場合は インストール を先にどうぞ。SlideCraft の考え方（書く → 見る → 出す）は各ページ冒頭でも触れています。
スライド区切り ---
---（水平線）だけの行が 1 枚のスライドの境界です。区切りごとに 1 枚のスライドが生成されます。
# 最初のスライド
- ポイント1
- ポイント2
---
# 次のスライド
本文テキスト。上の例は 2 枚のスライドになります。区切りは行頭が --- の行そのものです。GFM 表の区切り行（|---|---|）はセルの縦棒を伴うので、スライド区切りと混同されません。
TIP
先頭に空行があっても大丈夫です。区切りが残す先頭の空行はパーサが読み飛ばします。
タイトル・サブタイトル・本文
1 枚のスライドの中身は、見出しレベルと行の種類で役割が決まります。
| 記法 | 役割 |
|---|---|
# 見出し | スライドのタイトル |
## 見出し または > 引用 | サブタイトル |
- / * の箇条書き、段落 | 本文 |
### 見出し | グループ（カラム/カード/ステップ）内の小見出し |
**太字** / *斜体* | インライン装飾 |
# 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 -->
# 表紙タイトル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は画像を最背面に敷きます。背景写真や地紋の上に本文を載せる用途に向きます。
カラム分割スライドでも背景画像は使える
<!-- col --> などで分割したスライドでも、単独の画像行（特に behind=1 の背景）は各カラムの本文に取り込まれず、スライド全体の背景として扱われます。
多カラム / KPI / ステップ / カード
1 枚のスライドの本文を複数の領域に分けたいときは、区切りコメントを使います。# タイトル の後に同じ種類の区切りコメントを並べ、その間に各領域の内容を書きます。
| 区切りコメント | 用途 |
|---|---|
<!-- col --> | 横並びの複数カラム |
<!-- kpi --> | KPI（大きな数字）タイル |
<!-- step --> | プロセス／手順ステップ |
<!-- card --> | カード |
# 3本柱
<!-- col -->
### 品質
- 不良率を半減
<!-- col -->
### 速度
- リードタイム短縮
<!-- col -->
### コスト
- 原価 10% 削減使い方のポイント：
- 区切りコメントはそれだけの行（
<!-- col -->のように前後に本文を書かない）にします。 - 最初の区切りコメントより前に書いた内容は、タイトル／サブタイトル以外は各領域には入りません。タイトル（
#）とサブタイトル（>）はスライド全体の見出しになり、各領域の中身は区切りのあいだに書きます。 - 各領域では
### 小見出しが領域のヘッダになり、その下に箇条書きや段落を書きます。 col（素のカラム）以外のkpi/step/cardは、対応するレイアウト（KPI タイル・プロセス・カード）を選ぶヒントになります。colはヒントを持たない素の横並びです。
領域に図を置く
各領域には本文の代わりに図を置くこともできます。領域の中に ```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設定）。