Markdown 仕様

figdeck が対応する Markdown 記法の仕様です。

スライド区切り

---（thematicBreak、水平線）でスライドを区切ります。

# スライド1

内容

---

# スライド2

内容

YAML Frontmatter

YAML frontmatter を使用してスライドの設定を行えます。設定には2種類あります：

グローバル設定

ファイルの先頭（コンテンツの前）に配置した設定は、すべてのスライドにデフォルトとして適用されます。

---
figdeck: true
background: "#1a1a2e"
color: "#ffffff"
transition: dissolve
---

# 最初のスライド

---

## 2番目のスライド

この例では、すべてのスライドにダークな背景、白いテキスト、dissolve トランジションが適用されます。

スライドごとの設定

スライド区切り（---）の直後に配置した設定は、そのスライドのみに適用され、グローバル設定を上書きします。

---
background: "#1a1a2e"
transition: dissolve
---

# 最初のスライド

グローバル設定を使用（ダーク背景、dissolve）

---
background: "#ffffff"
color: "#000000"
transition: slide-from-right
---

## 2番目のスライド

このスライドは白い背景、黒いテキスト、右からスライドイン

---

## 3番目のスライド

グローバル設定に戻る（ダーク背景、dissolve）

利用可能な設定

設定	説明
`figdeck`	VSCode 拡張機能の機能を有効化（`true`/`false`）
`cover`	1枚目を表紙として扱う（`true`/`false`、デフォルト: `true`）
`background`	統合背景設定：色、グラデーション、画像、テンプレート、Figma コンポーネント
`color`	ベーステキスト色
`headings`	見出しスタイル（h1, h2, h3, h4）
`paragraphs`	段落スタイル
`bullets`	箇条書きスタイル
`code`	コードブロックスタイル
`fonts`	カスタムフォント設定
`align`	水平方向の配置（left, center, right）
`valign`	垂直方向の配置（top, middle, bottom）
`transition`	スライドトランジションアニメーション
`slideNumber`	スライド番号設定
`titlePrefix`	タイトルプレフィックスコンポーネント

各設定の詳細は、以下の各セクションを参照してください。

見出し

H1 (`#`) - タイトルスライド

# で始まる見出しはタイトルスライドを作成します。フォントサイズは 64px で大きく表示されます。

# プレゼンテーションタイトル

H2 (`##`) - コンテンツスライド

## で始まる見出しはコンテンツスライドを作成します。フォントサイズは 48px です。

## アジェンダ

H3 以下 (`###`, `####`, …)

H3 以下の見出しはスライド内のサブ見出しとして表示されます。

本文

段落テキストはスライド上の本文コンテンツとして表示されます。複数の段落は改行で区切られて表示されます。

## スライドタイトル

これは本文です。

これも本文に追加されます。

箇条書き

リスト（-, *, + または数字）は箇条書きとして表示されます。

順序なしリスト

表示時に • が先頭に付きます。

## 特徴

- 高速
- シンプル
- 拡張性

順序付きリスト

数字で始まるリストは番号付きリストとして表示されます。 start 属性で開始番号を指定できます。

1. 最初のステップ
2. 次のステップ
3. 最後のステップ

ネストしたリスト

2スペースのインデントでリストをネストできます。ネストレベルに応じてバレットマーカーが変わります：

レベル 0: • (U+2022)
レベル 1: ◦ (U+25E6)
レベル 2: ▪ (U+25AA)
レベル 3+: – (U+2013)

## ネストの例

- 親項目
  - 子項目（2スペースインデント）
    - 孫項目
      - ひ孫項目
- 親レベルに戻る

箇条書きの間隔

YAML frontmatter の spacing プロパティで箇条書き項目間の間隔をカスタマイズできます：

---
bullets:
  spacing: 16  # 箇条書き項目間の間隔（デフォルト: 8px）
---

## 広い間隔

- 項目 1
- 項目 2
- 項目 3

spacing の値はピクセル単位です。デフォルトは 8px です。

インラインフォーマット

テキスト内で以下の書式を使用できます：

太字: **テキスト** または __テキスト__
イタリック: *テキスト* または _テキスト_
~~取り消し線~~: ~~テキスト~~ (GFM)
インラインコード: `コード`
リンク: [テキスト](URL)

これらは組み合わせることも可能です：

これは **太字** と *イタリック* と ~~取り消し線~~ のテスト。

`const x = 1` はインラインコードです。

[Figmaへ](https://figma.com) のリンク。

引用 (Blockquote)

> で始まる行は引用ブロックとして表示されます。左側にグレーのボーダーが付き、やや淡い色で表示されます。

> これは引用文です。
> 複数行にまたがることもできます。

コールアウト

コールアウトは、メモ、ヒント、警告、注意などのスタイル付きメッセージブロックです。 :::note、:::tip、:::warning、:::caution ディレクティブ構文を使用します：

:::note
これは重要な情報を含むメモです。
:::

:::tip
ユーザーへの便利なヒントです。
:::

:::warning
この機能には注意が必要です。
:::

:::caution
この操作は元に戻せません！
:::

各コールアウトタイプは異なる色で表示されます：

Note (青): 一般的な情報やコンテキスト
Tip (緑): 便利な提案やベストプラクティス
Warning (オレンジ): 注意が必要な重要な情報
Caution (赤): 潜在的な問題に関する重要な警告

コールアウトは太字、イタリック、リンク、インラインコードなどのインライン書式をサポートしています：

:::tip
**デバッグ**には `console.log()` を使用してください。
詳細は[ドキュメント](https://example.com)を参照してください。
:::

背景

background プロパティは、すべての背景タイプを統合した設定です。文字列形式（自動検出）またはオブジェクト形式（明示的）で指定できます。

文字列形式（自動検出）

---
# 単色（16進数）
background: "#1a1a2e"

# グラデーション
background: "#0d1117:0%,#1f2937:50%,#58a6ff:100%@45"

# 画像（ローカルパスまたはURL）
background: "./bg.png"
background: "https://example.com/bg.png"

# Figma コンポーネント（node-id 付きURL）
background: "https://www.figma.com/design/YOUR_FILE_KEY?node-id=123-456"
---

オブジェクト形式（明示的）

---
background:
  color: "#1a1a2e"           # 単色
  gradient: "#000:0%,#fff:100%@45"  # グラデーション
  template: "Dark Mode"      # Figma ペイントスタイル名
  image: "./bg.png"          # 画像パスまたはURL
  component:                 # Figma コンポーネント
    link: "https://www.figma.com/design/xxx?node-id=123-456"
    fit: "cover"             # cover | contain | stretch
    align: "center"          # center | top-left | top-right | bottom-left | bottom-right
    opacity: 0.8             # 0-1
---

背景の組み合わせ

コンポーネントは color/gradient/image 背景と組み合わせて使用できます。コンポーネントは上位レイヤーとして描画されます：

---
background:
  color: "#1a1a2e"
  component:
    link: "https://www.figma.com/design/xxx?node-id=123-456"
    opacity: 0.6
---

優先順位

オブジェクト形式で複数のプロパティを指定した場合の優先順位: template > gradient > color > image

コンポーネントの fit オプション

値	説明
`cover`	スライド全体を覆うようにスケール、はみ出し部分はクリップ（デフォルト）
`contain`	スライド内に収まるようにスケール、余白が生じる場合あり
`stretch`	スライドサイズに合わせて引き伸ばし、アスペクト比は維持されない

コンポーネントの align オプション

cover または contain 使用時に配置位置を指定できます：

値	説明
`center`	スライドの中央（デフォルト）
`top-left`	左上隅
`top-right`	右上隅
`bottom-left`	左下隅
`bottom-right`	右下隅

制限事項

コンポーネントは同一 Figma ファイル内のノードのみ対応（MVP 制限）
対応ノードタイプ: Component, ComponentSet, Frame, Instance
推奨背景サイズ: 1920x1080（スライドサイズ）

画像

![alt](url) 形式で画像を挿入できます。

リモート画像

![サンプル画像](https://example.com/image.png)

リモート URL（http:// または https:// で始まる）はプラグイン側でフェッチし、createImage に渡して表示します（PNG/JPEG/GIF のみ）。

ローカル画像

![ローカル画像](./images/photo.jpg)
![絶対パス](../assets/logo.png)

ローカルファイルパス（URL スキームなし）は CLI が自動的に検出し、ファイルを読み込んで base64 エンコードしてプラグインに送信します。パスは Markdown ファイルからの相対パスとして解決されます。

対応フォーマット: .jpg, .jpeg, .png, .gif

サイズ制限: デフォルトで 5MB まで。これを超えるファイルはスキップされ、警告が表示されます。

画像サイズ指定（Marp 互換）

alt テキスト内で Marp 互換の構文を使用して画像サイズを指定できます：

![w:400](./image.png)           # 幅 400px（高さは自動計算）
![h:300](./image.png)           # 高さ 300px（幅は自動計算）
![w:400 h:300](./image.png)     # 固定サイズ 400x300px
![w:50%](./image.png)           # スライド幅の 50%（960px）
![w:400 ロゴ](./image.png)      # サイズ指定 + alt テキスト

動作:

w: のみ: アスペクト比を維持して高さを自動計算
h: のみ: アスペクト比を維持して幅を自動計算
両方指定: 指定サイズで表示（アスペクト比は維持されない場合あり）
パーセンテージ: スライド幅（1920px）を基準に計算
サイズ未指定: デフォルトの最大制約（400x300px）を適用

画像位置指定（絶対配置）

画像をスライド上の特定の位置に配置するために、絶対座標 x/y を指定できます：

![x:100 y:200](./image.png)           # (100px, 200px) の位置に配置
![x:50% y:50%](./image.png)           # スライドの中央（パーセンテージ）
![w:300 x:100 y:200](./image.png)     # サイズ + 位置
![w:300 x:100 y:200 商品](./image.png)  # サイズ + 位置 + alt テキスト

動作:

x: または y: を指定すると、画像は自動レイアウトフローではなく絶対座標に配置されます
x: のみ指定した場合、y は 0 になります（逆も同様）
パーセンテージ: x: はスライド幅（1920px）、y: はスライド高さ（1080px）を基準に計算
例: x:50% = 960px, y:50% = 540px

ユースケース:

背景画像の上に画像をオーバーレイ
横並びレイアウト
ロゴやアイコンの精密な配置
複数画像の複雑なコンポジション

フォールバック

画像の読み込みに失敗した場合（ファイルが見つからない、ネットワークエラーなど）は、プレースホルダーとして表示されます。 alt テキストまたは URL がラベルとして表示されます。

Figma Selection Link

:::figma ブロックを使用すると、Figma ノードへのリンクカードをスライドに埋め込めます。同一ファイル内のノードの場合、クリックするとそのノードに直接ジャンプします。

基本構文

:::figma
link=https://www.figma.com/file/xxx/name?node-id=1234-5678
:::

プロパティ

プロパティ	必須	説明
`link`	✅	Figma の URL（node-id パラメータ付き）
`x`	-	カードの X 座標（省略時は自動配置）
`y`	-	カードの Y 座標（省略時は自動配置）
`hideLink`	-	プレビュー下のリンクラベルを非表示（`true`）
`text.*`	-	テキストレイヤーの上書き（後述）

テキストレイヤーの上書き

text.* プロパティを使用して、Figma コンポーネント内のテキストコンテンツを上書きできます。 * はレイヤー名に置き換えます（大文字小文字を区別しません）。

:::figma
link=https://www.figma.com/file/xxx?node-id=1234-5678
text.title=カート機能
text.body=カートと確認フローに使用します。
:::

リッチテキストフォーマット がテキスト上書き内でサポートされています：

:::figma
link=https://www.figma.com/file/xxx?node-id=1234-5678
text.description=これは **太字** と *イタリック* のテキストで、[リンク](https://example.com)も含みます。
:::

複数行テキスト と箇条書き：

:::figma
link=https://www.figma.com/file/xxx?node-id=1234-5678
text.content=
  - バリエーション A
  - バリエーション B
  - バリエーション C
:::

テキスト上書きでサポートされるフォーマット：

太字: **テキスト**
イタリック: *テキスト*
取り消し線: ~~テキスト~~
リンク: [テキスト](url)
箇条書き: - 項目
引用: > 引用 （引用符付きイタリックとして表示）

注意: コードブロックは Figma テキストレイヤーの制限により、テキスト上書きではサポートされていません。

位置指定の例

:::figma
link=https://www.figma.com/file/xxx?node-id=1234-5678
x=160
y=300
:::

動作

同一ファイル: node-id が現在のファイル内に存在する場合、コンポーネントがクローンされプレビューとして表示されます
他ファイル: 異なるファイルの場合は URL ハイパーリンク付きのリンクカードを表示します
ノード未検出: 指定された node-id が見つからない場合は警告を表示し、URL フォールバックを使用します
テキスト上書き: text.* レイヤー名に一致するテキストレイヤーは、指定されたコンテンツとフォーマットで更新されます

サポートされる URL 形式

https://www.figma.com/file/<fileKey>/<name>?node-id=<nodeId>
https://www.figma.com/design/<fileKey>/<name>?node-id=<nodeId>
https://figma.com/file/<fileKey>?node-id=<nodeId>

node-id パラメータは 1234-5678 または 1234:5678、URL エンコード形式 1%3A2 いずれも対応しています。

テーブル (GFM)

GitHub Flavored Markdown のテーブル記法をサポートしています。

| 機能 | 説明 |
|------|------|
| パース | Markdown を解析 |
| 変換 | Figma Slides に変換 |

アラインメントも指定可能です：

| 左寄せ | 中央 | 右寄せ |
|:-------|:----:|-------:|
| テキスト | テキスト | 数値 |

マルチカラムレイアウト

:::columns ブロックを使用して、複数カラムのレイアウト（2〜4カラム）を作成できます。

基本構文

:::columns
:::column
左カラムのコンテンツ
:::column
右カラムのコンテンツ
:::

プロパティ

プロパティ	デフォルト	説明
`gap`	32	カラム間の隙間（ピクセル、最大: 200）
`width`	均等	カラム幅（fr、%、px 値を `/` で区切る）

2カラムレイアウト

:::columns
:::column
### 機能

- 高速レンダリング
- ライブプレビュー
- 簡単操作

:::column
### メリット

- 時間短縮
- 一貫したデザイン
- バージョン管理対応
:::

3カラムレイアウト

:::columns
:::column
**ステップ1**

企画
:::column
**ステップ2**

開発
:::column
**ステップ3**

展開
:::

4カラムレイアウト

:::columns
:::column
Q1: ¥1.2億
:::column
Q2: ¥1.8億
:::column
Q3: ¥2.1億
:::column
Q4: ¥2.5億
:::

カスタムギャップ

:::columns gap=64
:::column
より広い
:::column
スペース
:::

カスタム幅比率

fr（比率単位）、%（パーセント）、px（ピクセル）が使用可能：

:::columns width=1fr/2fr
:::column
### サイドバー (1/3)

ナビゲーション
:::column
### メインコンテンツ (2/3)

主要コンテンツエリア
:::

:::columns width=30%/70%
:::column
サイドバー
:::column
メインコンテンツ
:::

カラム内でサポートされるコンテンツ

各カラムには以下のコンテンツを含めることができます：

インラインフォーマット付きの段落（太字、斜体、コード、リンク）
箇条書きリスト（順序付き・順序なし）
構文ハイライト付きコードブロック
画像（サイズ制約あり）
テーブル
引用ブロック
見出し（H3、H4）

フォールバック動作

2カラム未満の場合、コンテンツは線形にレンダリングされます（カラムなし）
4カラムを超える場合、最初の4カラムのみ使用されます
カラム幅が最小値（320px）を下回る場合、カラムは垂直に積み重ねられます

脚注 (Footnotes)

GFM の脚注記法をサポートしています。脚注はスライドの下部に小さいフォントで表示されます。

基本構文

## 研究結果

最新の研究によると[^1]、これは重要な発見です[^2]。

[^1]: Smith et al. (2024) Journal of Science
[^2]: 詳細は付録Aを参照

名前付き脚注

数字の代わりに名前を使用することもできます：

この機能は便利です[^note]。

[^note]: ユーザビリティ調査により検証済み

表示形式

本文中の脚注参照は [1] や [note] のように角括弧で表示されます（Figma Slides は上付き文字をサポートしていないため）
脚注定義はスライド下部に水平線で区切られて表示されます
脚注内でも太字や イタリック などのインラインフォーマットが使用できます

スライドトランジション

スライド間のトランジションアニメーションを設定できます。

基本設定（ショートハンド）

---
transition: dissolve
---

duration を指定することもできます：

---
transition: slide-from-right 0.5
---

詳細設定

---
transition:
  style: slide-from-right   # アニメーションスタイル
  duration: 0.5             # 再生時間（秒）0.01〜10
  curve: ease-out           # イージングカーブ
  timing:
    type: after-delay       # on-click または after-delay
    delay: 2                # 自動再生までの待機時間（秒）0〜30
---

グローバル設定

ファイル先頭の frontmatter でグローバルトランジションを設定できます：

---
transition:
  style: dissolve
  duration: 0.5
  curve: ease-out
---

# タイトルスライド

---

## コンテンツスライド

この場合、すべてのスライドに dissolve トランジションが適用されます。

スライド個別の上書き

グローバル設定を個別のスライドで上書きできます：

---
transition: dissolve
---

# タイトル

---
transition: slide-from-right
---
## このスライドだけ右からスライドイン

transition: none でトランジションを無効化できます。

利用可能なスタイル

カテゴリ	スタイル
基本	`none`, `dissolve`, `smart-animate`
スライドイン	`slide-from-left`, `slide-from-right`, `slide-from-top`, `slide-from-bottom`
プッシュ	`push-from-left`, `push-from-right`, `push-from-top`, `push-from-bottom`
ムーブイン	`move-from-left`, `move-from-right`, `move-from-top`, `move-from-bottom`
スライドアウト	`slide-out-to-left`, `slide-out-to-right`, `slide-out-to-top`, `slide-out-to-bottom`
ムーブアウト	`move-out-to-left`, `move-out-to-right`, `move-out-to-top`, `move-out-to-bottom`

利用可能なイージングカーブ

カーブ	説明
`ease-in`	ゆっくり始まり加速
`ease-out`	減速して終わる
`ease-in-and-out`	ゆっくり始まりゆっくり終わる
`linear`	一定速度
`gentle`	なめらか
`quick`	素早く
`bouncy`	弾む
`slow`	ゆっくり

タイミング

タイプ	説明
`on-click`	クリックで次のスライドへ（デフォルト）
`after-delay`	指定秒数後に自動で次のスライドへ

注意: after-delay はプレゼンテーションモードでのみ動作します。

カスタムフォント

スライド内の各テキスト要素にカスタムフォントファミリーを設定できます。

基本設定

---
fonts:
  h1: "Roboto"                    # ショートハンド: ファミリー名のみ（"Regular" スタイルを使用）
  h2: "Open Sans"
  body: "Source Sans Pro"
  bullets: "Inter"
---

詳細設定

フォントバリアントを完全に制御するには、オブジェクト構文を使用します：

---
fonts:
  h1:
    family: "Roboto"
    style: "Medium"               # ベーススタイル（デフォルト: "Regular"）
    bold: "Bold"                  # 太字バリアント（デフォルト: "Bold"）
    italic: "Italic"              # イタリックバリアント（デフォルト: "Italic"）
    boldItalic: "Bold Italic"     # 太字イタリックバリアント
  body:
    family: "Source Sans Pro"
    style: "Regular"
    bold: "Semibold"              # カスタム太字バリアント
---

対応要素

要素	説明
`h1`	H1 見出し（タイトルスライド）
`h2`	H2 見出し（コンテンツスライドタイトル）
`h3`	H3 サブ見出し
`h4`	H4 サブ見出し
`body`	本文段落
`bullets`	箇条書き項目
`code`	コードブロックとインラインコード

フォントバリアント

プロパティ	説明	デフォルト
`family`	フォントファミリー名（例: “Roboto”）	必須
`style`	ベースフォントスタイル	”Regular”
`bold`	太字バリアントのスタイル名	”Bold”
`italic`	イタリックバリアントのスタイル名	”Italic”
`boldItalic`	太字イタリックバリアントのスタイル名	”Bold Italic”

フォールバック動作

リクエストされたフォントが Figma で利用できない場合：

警告通知が表示されます
プラグインはデフォルトフォントの Inter にフォールバックします
スライドは正常にレンダリングを続けます

スライド個別の上書き

スライド毎にフォントを上書きできます：

---
fonts:
  h1: "Roboto"
  body: "Source Sans Pro"
---

# デフォルトフォントのスライド

---
fonts:
  h1: "Georgia"
  body: "Times New Roman"
---

# このスライドは異なるフォントを使用

コードブロック

``` で囲まれたブロックはコードブロックとして表示されます。言語を指定するとシンタックスハイライトが適用されます。

` ```typescript
const message: string = "Hello, World!";
console.log(message);
` ```

対応言語: TypeScript, JavaScript, Python, Bash, JSON, CSS, HTML, XML, Go, Rust, SQL

完全な例

---
# figdeck プレゼンテーション

Markdown から Figma Slides へ

---
## 目次

- 概要
- 機能紹介
- デモ
- まとめ

---
## 概要

figdeck は Markdown ファイルを
Figma Slides に変換するツールです。

CLI と Figma Plugin が連携して動作します。

---
## 機能

- Markdown パース
- WebSocket 通信
- 自動スライド生成

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

質問はありますか？

この例は以下の 5 つのスライドを生成します：

タイトルスライド「figdeck プレゼンテーション」
コンテンツスライド「目次」（箇条書き4項目）
コンテンツスライド「概要」（本文2段落）
コンテンツスライド「機能」（箇条書き3項目）
タイトルスライド「ありがとうございました」

対応状況

記法	対応状況	備考
見出し (H1-H4)	✅	H1/H2はスライドタイトル
段落	✅
箇条書き	✅	順序付き/なし両対応
太字	✅
イタリック	✅
~~取り消し線~~	✅	GFM
`インラインコード`	✅	背景色付き
リンク	✅	クリック可能
引用	✅	左ボーダー付き
コードブロック	✅	シンタックスハイライト
テーブル	✅	GFM、アラインメント対応
画像	✅	ローカル・リモート対応
Figma リンク	✅	`:::figma` ブロック
align/valign	✅	スライド配置設定
脚注	✅	GFM、スライド下部に表示
トランジション	✅	スライド切り替えアニメーション
カスタムフォント	✅	要素ごとのフォントファミリー
背景コンポーネント	✅	Figma コンポーネント/フレームを背景に

Markdown 仕様

スライド区切り

YAML Frontmatter

グローバル設定

スライドごとの設定

利用可能な設定

見出し

H1 (#) - タイトルスライド

H2 (##) - コンテンツスライド

H3 以下 (###, ####, …)

本文

箇条書き

順序なしリスト

順序付きリスト

ネストしたリスト

箇条書きの間隔

インラインフォーマット

引用 (Blockquote)

コールアウト

背景

文字列形式（自動検出）

オブジェクト形式（明示的）

背景の組み合わせ

優先順位

コンポーネントの fit オプション

コンポーネントの align オプション

制限事項

画像

リモート画像

ローカル画像

画像サイズ指定（Marp 互換）

画像位置指定（絶対配置）

フォールバック

Figma Selection Link

基本構文

プロパティ

テキストレイヤーの上書き

位置指定の例

動作

サポートされる URL 形式

テーブル (GFM)

マルチカラムレイアウト

基本構文

プロパティ

2カラムレイアウト

3カラムレイアウト

4カラムレイアウト

カスタムギャップ

カスタム幅比率

カラム内でサポートされるコンテンツ

フォールバック動作

脚注 (Footnotes)

基本構文

名前付き脚注

表示形式

スライドトランジション

基本設定（ショートハンド）

詳細設定

グローバル設定

スライド個別の上書き

利用可能なスタイル

利用可能なイージングカーブ

タイミング

カスタムフォント

基本設定

詳細設定

対応要素

フォントバリアント

フォールバック動作

スライド個別の上書き

コードブロック

完全な例

対応状況

H1 (`#`) - タイトルスライド

H2 (`##`) - コンテンツスライド

H3 以下 (`###`, `####`, …)