Fancy Kanban 看板結構

一個基於 Markdown 的看板格式的獨立規範。任何讀寫符合此結構之檔案的應用程式，都能產生相容的看板。

概述

每個看板都位於一個帶有標識符 fancy-kanban 的圍欄式程式碼區塊中。這表示：

看板可以嵌入到筆記中的任何位置，與文本、連結和其他內容共存
一則筆記可以包含零個、一個或多個看板
僅由一個看板區塊組成的檔案即為獨立的看板檔案
若未安裝外掛，該區塊會呈現為無樣式的程式碼區塊 — 原始文字仍保持完全可讀

該區塊包含由 --- 分隔的兩個部分：

一個設定區段（類似 YAML），定義欄位、工作流程和檢視選項
一個Markdown 表格，包含資料行

完整範例

```fancy-kanban
---
title: 我的看板
fields:
  - name: title,       type: Text,     label: 標題
  - name: status,      type: Select,   options: inbox|doing|done, label: 狀態, default: inbox
  - name: responsible, type: Text,     label: 負責人
  - name: start_date,  type: Date,     label: 開始日期
  - name: notes,       type: Textarea, label: 備註
  - name: effort,      type: Number,   label: 工作量
  - name: docs,        type: Link,     label: 文件
  - name: team,        type: Select,   options: frontend|backend, label: 團隊
card_fields: responsible, effort
lanes: team
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
---

| _id    | 標題          | 狀態 | 負責人 | 開始日期   | 備註                         | 工作量 | 文件                   | 團隊     |
|--------|----------------|--------|-------------|------------|-------------------------------|--------|------------------------|----------|
| x7k2a1 | 修復登入錯誤  | inbox  | Alice       | 2026-01-15 | 需要調查                     | 3      |                        | backend  |
| m3p9b2 | 重構驗證模組  | doing  | Bob         |            | 多行內容<br>在此               | 5      | design.md              | backend  |
| q1r4c3 | 設定 CI       | done   |             | 2026-01-01 |                               | 1      | setup.md|guide.md    | frontend |
```

區塊結構

圍欄區塊正好包含兩個部分，由 --- 行分隔：

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

{markdown table}


第一個 `---` 之前的所有內容都會被忽略（保留給未來使用）。兩個 `---` 行之間的所有內容是設定區段。第二個 `---` 之後的所有內容是表格。

## 設定區段

類似 YAML 的鍵值對。逐行解析。

### 鍵

| 鍵 | 必填 | 預設值 | 描述 |
|-----|----------|---------|-------------|
| `title` | 是 | — | 人類可讀的看板名稱 |
| `fields` | 是 | — | 欄位定義列表（見下文） |
| `version` | 否 | `1` | 由外掛寫入的格式版本；版本高於當前外掛支援的看板將以唯讀模式開啟 |
| `workflow` | 否 | 允許所有轉換 | 逗號分隔的 `from→to` 配對 |
| `lanes` | 否 | 無 | 用作泳道分組維度的欄位名稱 |
| `card_title` | 否 | 自動偵測 | 用作卡片標題的欄位名稱；設為空字串則不顯示標題 |
| `card_fields` | 否 | 無 | 在卡片標題下方顯示的次要欄位的有序逗號分隔清單 |
| `card_labels` | 否 | `true` | 設為 `false` 以隱藏次要卡片欄位的標籤前綴 |
| `card_limit` | 否 | `0`（無限制） | 每欄顯示的最大卡片數量；超過此數量的卡片會隱藏在「顯示更多」按鈕之後 |

### `card_title`

```yaml
card_title: summary

控制哪個欄位被呈現為卡片標題：

缺席（預設）：自動使用第一個非 _id、非欄位的欄位
設定為欄位名稱：該欄位的值作為標題顯示
設為空字串（card_title: ）：不顯示標題；卡片僅顯示次要欄位

`card_fields`

card_fields: priority, due, docs

一個有序的逗號分隔清單，列出要在卡片標題下方顯示的次要欄位名稱。它們以帶有標籤的行形式顯示在標題下方。

預設行為：當 card_fields 缺席時，卡片僅顯示標題欄位。沒有 card_fields 鍵的現有看板不受影響。

未知名稱：不符合任何已定義欄位的欄位名稱在渲染時會被靜默忽略。從 fields: 中移除欄位會自動將其從卡片顯示中隱藏，而不會產生解析錯誤。

連結欄位：當 Link 欄位包含在 card_fields 中時，其項目會在卡片上呈現為可點擊連結的水平列表。儲存庫路徑會在新分頁中開啟；外部 URI 會在瀏覽器中開啟。

`card_labels`

card_labels: false

當設為 false 時，次要欄位行上的標籤前綴會被省略 — 僅顯示值。預設為 true（標籤可見）。僅當值為 false 時，該鍵才會寫入設定。

`card_limit`

card_limit: 5

當設為正整數時，每欄最多顯示該數量的卡片。超出限制的卡片會被隱藏，並在欄底出現一個 顯示更多 (N) 按鈕。點擊該按鈕會顯示所有剩餘卡片，無需重新載入看板。設定 card_limit: 0 或省略該鍵則完全停用限制。

這對於已完成欄位隨著時間累積大量已完成卡片的看板特別有用 — 最新加入的卡片仍能一目了然，而較舊的歷史記錄則會摺疊起來。

`lanes`

當設為一個欄位名稱（必須是 Select 欄位）時，看板會呈現為一個矩陣：

欄位 — 由 status 欄位的 options 順序驅動
泳道行 — 由 lanes 欄位的 options 順序驅動

沒有任何 lanes 欄位值的卡片會出現在底部的 未指派 偽泳道中。更改 lanes 僅為檢視設定變更 — 不影響任何行資料。

欄位定義

fields 列表中的每個條目都是同一行上的一組逗號分隔的 key: value 配對，並以 - 為前綴：

fields:
  - name: title, type: Text, label: 標題
  - name: status, type: Select, options: inbox|doing|done, label: 狀態, 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
`default`	否	新卡片的預設值

欄位類型

類型	儲存格式	描述
`Text`	純字串	單行文字
`Textarea`	字串，換行以 `<br>` 表示	多行文字
`Date`	`YYYY-MM-DD`	日期
`Number`	整數或小數字串	數值
`Select`	`options` 中的一個值	受限選擇；選項可透過 `colors` 屬性攜帶十六進制顏色
`Link`	以 `<br>` 分隔的路徑或 URI 列表	相對於儲存庫根目錄的路徑（`notes/doc.pdf`）或外部 URI（`https://…`、`ftp://…`、`mailto:…`）

特殊欄位名稱

名稱	角色
`title`	主要顯示欄位。應在 `fields:` 中第一個列出。當 `card_title` 未設定時，用作自動偵測的卡片標題。
`status`	必要。看板欄位。必須為 `type: Select`。卡片根據此值分組到各個欄位中。欄位順序遵循 `options` 順序。

所有其他欄位都是次要的 — 當列在 card_fields 中時，顯示為卡片後設資料。

項目身份

每張卡片都有一個穩定的隱藏 ID，儲存在 Markdown 表格的 _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
軟體	`backlog	todo
內容	`idea	draft
專案	`planning	active
自訂	使用者定義	使用者定義

選擇自訂會開啟一個用於 status 選項和工作流程轉換的自由格式編輯器。

Markdown 表格

表格緊接在設定區段的結尾 --- 之後出現。

結構

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

標題行 — 第一欄始終是 _id；其餘欄位按結構定義順序排列的欄位標籤
分隔行 — 標準的 Markdown 表格分隔行
資料行 — 每張卡片一行；_id 儲存格包含卡片的穩定 ID

規則

表格中的欄位順序必須符合欄位定義順序（在 _id 之後）
空的儲存格是有效的（欄位值 = 空字串）
狀態群組內的行順序即為顯示順序
空的表格（只有標題行 + 分隔行，沒有資料行）是有效的
_id 欄位始終是第一個，且永遠不會在渲染的看板中顯示

跳脫

值中的字元	跳脫為
`	` （豎線）
換行	`<br>`
回車	`<br>`

讀取時：| → |，<br> → 換行。寫入時：| → |，任何換行 → <br>。

解析演算法

提取 fancy-kanban 區塊的開頭和結尾圍欄之間的原始字串
在第一個 --- 行處分割，以定位設定區段的開頭
在第二個 --- 行處分割，將設定與表格分離
逐行解析設定：提取 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，然後按結構定義順序排列的欄位標籤
產生分隔行
每張卡片產生一個資料行：先 _id，然後按結構順序排列的欄位值，豎線和換行符被跳脫
如果卡片沒有現有 ID，則使用隨機字母數字字串為新卡片產生一個 _id
重建完整區塊：開頭圍欄、設定、---、空行、表格、結尾圍欄

**回寫原則：**僅修補來源檔案中受影響區塊的文字範圍 — 周圍內容永遠不會被重寫。

最小可行看板

```fancy-kanban
---
title: 我的看板
fields:
  - name: title, type: Text, label: 標題
  - name: status, type: Select, options: inbox|doing|done, label: 狀態, default: inbox
workflow: inbox→doing, inbox→done, doing→done, doing→inbox, done→doing, done→inbox
---

| _id | 標題 | 狀態 |
|-----|-------|--------|


## 相容性注意事項

- 沒有外掛的情況下，該區塊會呈現為純程式碼區塊 — 所有資料仍以純文字形式可見
- 區塊內的 Markdown 表格是有效的 Markdown，可在任何文字編輯器中閱讀
- 設定區段遵循靜態網站產生器和筆記應用程式熟悉的 YAML 慣例
- 移除外掛不會影響資料完整性，所有資料都可以復原

## 已棄用的功能

有關衝突、刪除或取代的功能，請參閱 [docs/deprecations.md](deprecations.md)。

robertoallende/fancy-kanban

fancy-kanban 是什麼？

在你喜歡的 AI 中提問

說明文件