Fancy Kanban ボードスキーマ

このMarkdownベースのかんばんボード形式の自己完結型仕様書です。このスキーマに従ってファイルを読み書きするアプリケーションは、互換性のあるボードを生成できます。

概要

各ボードは、fancy-kanbanという識別子を持つフェンスで囲まれたコードブロック内に配置されます。これは以下のことを意味します：

ボードは、散文、リンク、その他のコンテンツとともに、ノート内の任意の場所に埋め込むことができます
ノートには、0個、1個、または複数個のボードを含めることができます
単一のボードブロックのみで構成されるファイルは、スタンドアロンのボードファイルです
プラグインがインストールされていない場合、ブロックはスタイルのないコードブロックとしてレンダリングされます — 生のテキストは完全に人間が読めるままです

ブロックには、--- で区切られた2つのセクションが含まれます：

フィールド、ワークフロー、表示オプションを定義する設定セクション（YAML形式）
データ行を含むMarkdownテーブル

完全な例

```fancy-kanban
---
title: My Board
fields:
  - name: title,       type: Text,     label: Title
  - name: status,      type: Select,   options: inbox|doing|done, label: Status, default: inbox
  - name: responsible, type: Text,     label: Responsible
  - name: start_date,  type: Date,     label: Start Date
  - name: notes,       type: Textarea, label: Notes
  - name: effort,      type: Number,   label: Effort
  - name: docs,        type: Link,     label: Docs
  - name: team,        type: Select,   options: frontend|backend, label: Team
card_fields: responsible, effort
lanes: team
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
---

| _id    | Title          | Status | Responsible | Start Date | Notes                      | Effort | Docs                  | Team     |
|--------|----------------|--------|-------------|------------|----------------------------|--------|-----------------------|----------|
| x7k2a1 | Fix login bug  | inbox  | Alice       | 2026-01-15 | Needs investigation        | 3      |                       | backend  |
| m3p9b2 | Refactor auth  | doing  | Bob         |            | Multi-line\<br\>content here | 5      | design.md             | backend  |
| q1r4c3 | Setup CI       | done   |             | 2026-01-01 |                            | 1      | setup.md\|guide.md    | frontend |
```

ブロック構造

フェンスで囲まれたブロックには、--- 行で区切られた正確に2つのセクションが含まれます：

```fancy-kanban
---
{config}
---

{markdown table}


最初の `---` より前のすべては無視されます（将来の使用のために予約済み）。2つの `---` 行の間のすべてが設定です。2番目の `---` の後のすべてがテーブルです。

## 設定セクション

YAML風のキーと値のペア。行ごとに解析されます。

### キー

| キー | 必須 | デフォルト | 説明 |
|------|------|------------|------|
| `title` | はい | — | 人間が読めるボード名 |
| `fields` | はい | — | フィールド定義のリスト（以下を参照） |
| `version` | いいえ | `1` | プラグインによって書き込まれるフォーマットバージョン。現在のプラグインがサポートするよりも高いバージョンのボードは読み取り専用モードで開かれます。 |
| `workflow` | いいえ | すべての遷移を許可 | カンマ区切りの `from→to` ペア |
| `lanes` | いいえ | なし | スイムレーンのグループ化ディメンションとして使用するフィールド名 |
| `card_title` | いいえ | 自動検出 | カードの見出しとして使用するフィールド名。空文字列に設定すると見出しは表示されません。 |
| `card_fields` | いいえ | なし | カードの見出しの下に表示するセカンダリフィールドの順序付きカンマ区切りリスト |
| `card_labels` | いいえ | `true` | セカンダリカードフィールドのラベルプレフィックスを非表示にするには `false` に設定します。 |
| `card_limit` | いいえ | `0`（制限なし） | 列ごとに表示されるカードの最大数。この数を超えるカードは「Show more」ボタンの背後に隠れます。 |

### `card_title`

```yaml
card_title: summary

カードの見出しとしてレンダリングされるフィールドを制御します：

省略時（デフォルト）：最初の _id でも列フィールドでもないフィールドが自動的に使用されます
フィールド名に設定：そのフィールドの値が見出しとして表示されます
空文字列に設定（card_title: ）：見出しは表示されません。カードにはセカンダリフィールドのみが表示されます。

`card_fields`

card_fields: priority, due, docs

カードの見出しの下に表示する、順序付きカンマ区切りのセカンダリフィールド名のリストです。これらはタイトルの下にラベル付きの行として表示されます。

デフォルトの動作：card_fields がない場合、カードには見出しフィールドのみが表示されます。card_fields キーがない既存のボードには影響しません。

不明な名前：定義されたフィールドに一致しないフィールド名は、レンダリング時に自動的に無視されます。fields: からフィールドを削除すると、パースエラーなしで自動的にカード表面から非表示になります。

リンクフィールド：Link フィールドが card_fields に含まれている場合、そのアイテムはカード表面にクリック可能なリンクの水平リストとしてレンダリングされます。Vault内のパスは新しいタブで開き、外部URIはブラウザで開きます。

`card_labels`

card_labels: false

false に設定すると、セカンダリフィールド行からラベルプレフィックスが省略され、値のみが表示されます。デフォルトは true（ラベル表示）です。このキーは、値が false の場合にのみ設定に書き込まれます。

`card_limit`

card_limit: 5

正の整数に設定すると、各列に最大でその数のカードが表示されます。制限を超えたカードは非表示になり、列の下部に Show more (N) ボタンが表示されます。クリックすると、ボードを再読み込みせずに残りのすべてのカードが表示されます。card_limit: 0 に設定するか、キーを省略すると、制限が完全に無効になります。

これは、done 列に時間の経過とともに多くの完了したカードが蓄積されるボードで特に便利です — 最も最近追加されたカードは一目で見えるままになり、古い履歴は邪魔にならないように折りたたまれます。

`lanes`

フィールド名（Select フィールドである必要があります）に設定すると、ボードはマトリックスとしてレンダリングされます：

列 — status フィールドの options の順序に従います
スイムレーン行 — lanes フィールドの options の順序に従います

lanes フィールドの値がないカードは、下部の 未割り当て 疑似レーンに表示されます。lanes の変更は表示設定の変更のみであり、行データには影響しません。

フィールド定義

fields リストの各エントリは、1行に key: value ペアをカンマ区切りで並べ、先頭に - を付けます：

fields:
  - name: title, type: Text, label: Title
  - name: status, type: Select, options: inbox|doing|done, label: Status, default: inbox

フィールドの順序規則：最初に title、次に status、その後に追加のフィールドをリストします。データセクションのテーブル列の順序はフィールド定義の順序を反映し、自動検出されたカード見出しは最初の _id でも列フィールドでもないフィールドに解決されるため、title を最初に配置することで、明示的な card_title キーなしで予測可能な見出し解決が保証されます。

フィールドプロパティ

プロパティ	必須	説明
`name`	はい	内部識別子。小文字、スペースはアンダースコア。
`type`	はい	次のいずれか：`Text`、`Textarea`、`Date`、`Number`、`Select`、`Link`
`label`	はい	人間が読める列ヘッダー。Markdownテーブルのヘッダーと完全に一致する必要があります。
`options`	Selectのみ	許可される値のパイプ区切り（`\|`）リスト
`colors`	Select、オプション	各オプションに背景色を割り当てる `name=hex` ペアのパイプ区切りリスト（例：`High=#e74c3c\|Low=#27ae60`）。エントリのないオプションはプレーンテキストとしてレンダリングされます。
`default`	いいえ	新しいカードのデフォルト値

フィールドタイプ

タイプ	保存形式	説明
`Text`	プレーン文字列	単一行テキスト
`Textarea`	改行を `<br>` で表現する文字列	複数行テキスト
`Date`	`YYYY-MM-DD`	カレンダー日付
`Number`	整数または小数の文字列	数値
`Select`	`options` 値のいずれか	制約された選択肢。`colors` プロパティにより16進色を保持できます。
`Link`	パスまたはURIの `<br>` 区切りリスト	Vaultルート相対パス（`notes/doc.pdf`）または外部URI（`https://…`、`ftp://…`、`mailto:…`）

特別なフィールド名

名前	役割
`title`	プライマリ表示フィールド。 `fields:` の最初にリストする必要があります。`card_title` が設定されていない場合の自動検出されるカード見出しとして使用されます。
`status`	必須。かんばん列フィールド。 `type: Select` である必要があります。カードはこの値によって列にグループ化されます。列の順序は `options` の順序に従います。

他のすべてのフィールドはセカンダリであり、card_fields にリストされている場合にカードメタデータとして表示されます。

アイテムの識別子

すべてのカードには、Markdownテーブルの _id 列に保存された安定した非表示のIDがあります。UIはこの列を決して表示しません。

カード作成時に生成：短いランダムな英数字文字列（例：8文字：x7k2a1b3）
すべてのシリアライズのラウンドトリップを通じて保持されます
並べ替え、ドラッグ＆ドロップ、フィールド名変更後も存続します
すべてのカード操作（移動、編集、削除）に内部的に使用されます

IDベースでアイデンティティが保持され、コンテンツから派生しないため、カードのタイトルを変更してもそのアイデンティティには影響しません。

ワークフロー

UIで許可されるステータス遷移を定義します：

workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox

from→to ペアのカンマ区切りリスト（矢印：→、U+2192）
workflow が省略された場合、ステータスオプション間のすべての遷移が許可されます
UIの選択肢を制限するために使用されます（例：「移動先」メニューに有効なターゲットのみが表示されます）
生のテーブルへの手動編集は、プレーンテキストであるという性質上、ワークフローバリデーションをバイパスします

ボードテンプレート

新しいボードを作成するとき、一連の定義済みテンプレートが一般的な status オプションセットを提供します。テンプレートは status フィールドのオプションと workflow のみを事前入力します — その他のフィールドはユーザーが追加します。

テンプレート	ステータスオプション	デフォルトのワークフロー
基本	`inbox \| doing \| done`	すべての遷移
ソフトウェア	`backlog \| todo \| in-progress \| review \| done`	順方向＋1ステップ戻る
コンテンツ	`idea \| draft \| review \| published`	順方向のみ
プロジェクト	`planning \| active \| blocked \| complete`	すべての遷移（→ planning を除く）
カスタム	ユーザー定義	ユーザー定義

カスタム を選択すると、status オプションとワークフロー遷移のための自由形式エディタが開きます。

Markdownテーブル

テーブルは、設定セクションの終わりの --- の直後に表示されます。

構造

| _id    | Header1 | Header2 |
|--------|---------|---------|
| abc123 | value   | value   |

ヘッダー行 — 最初の列は常に _id。残りの列はスキーマ定義順のフィールドラベルです。
区切り行 — 標準的なMarkdownテーブルの区切り行
データ行 — カードごとに1行。_id セルにはカードの安定したIDが含まれます。

ルール

テーブルの列の順序は、フィールド定義の順序と一致している必要があります（_id の後）
空のセルは有効です（フィールド値 = 空文字列）
ステータスグループ内の行の順序が表示順序です
空のテーブル（ヘッダー＋区切り行、データ行なし）は有効です
_id 列は常に最初にあり、レンダリングされたボードには決して表示されません

エスケープ

値内の文字	エスケープ後
`\|` (パイプ)	`\|` (バックスラッシュ-パイプ)
改行	`<br>`
キャリッジリターン	`<br>`

読み取り時：\| → |、<br> → 改行。書き込み時：| → \|、任意の改行 → <br>。

解析アルゴリズム

fancy-kanban ブロックの開始と終了のフェンス間の生の文字列を抽出します。
最初の --- 行で分割し、設定セクションの開始位置を特定します。
2番目の --- 行で分割し、設定とテーブルを分離します。
設定を行ごとに解析：title、version、fields、workflow、lanes、card_title、card_fields、card_labels、card_limit を抽出します。
fields については、- で始まる行を収集し、それぞれをカンマ区切りの key: value ペアとして解析します。colors はパイプ区切りの name=hex トークンとしてデコードされます。
本文内のテーブル行（| で始まる行）を見つけます。
最初のテーブル行はヘッダー行です — 列ラベルを抽出します。_id は常に最初です。
残りのヘッダーラベルを、大文字小文字を区別しないラベル検索を介してフィールド名にマッピングします。
各データ行を解析：エスケープされていない | で分割し、セルをトリミングし、\| と <br> をアンエスケープします。
各データ行の最初のセルがカードの _id です。
status フィールドの値でカードをグループ化し、options の順序でグループをシードします。

スキーマ調整（解析後に適用）：

スキーマに存在するがカードのデータに欠けているフィールド：フィールドの default（または空文字列）でバックフィルします。
カードデータに存在するがスキーマから削除されたフィールド：孤立した非表示データとして保持します（削除されません）。

書き込みアルゴリズム

現在のスキーマから設定セクションを再構築します（可能な場合は元のフォーマットを保持します）。
ヘッダー行を生成：_id を最初に、次にスキーマ定義順のフィールドラベル。
区切り行を生成します。
カードごとに1つのデータ行を生成：_id を最初に、次にスキーマ順のフィールド値、パイプと改行はエスケープされます。
カードに既存のIDがない場合、ランダムな英数字文字列を使用して新しいカード _id を生成します。
完全なブロックを再構築：開始フェンス、設定、---、空行、テーブル、終了フェンス。

書き戻し原則： 影響を受けるブロックのテキスト範囲のみがソースファイル内でパッチされます。周囲のコンテンツは決して書き換えられません。

最小限のボード

```fancy-kanban
---
title: My Board
fields:
  - name: title, type: Text, label: Title
  - name: status, type: Select, options: inbox|doing|done, label: Status, default: inbox
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
---

| _id | Title | Status |
|-----|-------|--------|


## 互換性に関する注意

- プラグインがない場合、ブロックはプレーンなコードブロックとしてレンダリングされます — すべてのデータはプレーンテキストとして引き続き表示可能です。
- ブロック内のMarkdownテーブルは有効なMarkdownであり、任意のテキストエディタで読み取り可能です。
- 設定セクションは、静的サイトジェネレーターやノート作成アプリでおなじみのYAML規則に従います。
- プラグインを削除しても、すべてのデータはそのまま残り、復元可能です。

## 非推奨の機能

非推奨の機能については、[docs/deprecations.md](deprecations.md) を参照してください。

robertoallende/fancy-kanban

fancy-kanban とは？

お気に入りのAIに質問する

ドキュメント