Fancy Kanban Board Schema

A self-contained specification for the markdown-based kanban board format. Any app that reads and writes files following this schema will produce compatible boards.

Overview

Each board lives inside a fenced code block with the identifier fancy-kanban. This means:

• A board can be embedded anywhere in a note, alongside prose, links, and other content
• A note may contain zero, one, or multiple boards
• A file consisting of a single board block is a standalone board file
• Without the plugin installed, the block renders as an unstyled code block — the raw text remains fully human-readable

The block contains two sections separated by ---:

1. A config section (YAML-like) defining fields, workflow, and view options
2. A markdown table containing the data rows

Complete Example

```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 |
```

Block Structure

The fenced block contains exactly two sections divided by a --- line:

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

{markdown table}

Everything before the first `---` is ignored (reserved for future use). Everything between the two `---` lines is the config. Everything after the second `---` is the table.

## Config Section

YAML-like key-value pairs. Parsed line-by-line.

### Keys

| Key | Required | Default | Description |
|-----|----------|---------|-------------|
| `title` | yes | — | Human-readable board name |
| `fields` | yes | — | List of field definitions (see below) |
| `version` | no | `1` | Format version written by the plugin; boards with a version higher than the current plugin supports open in read-only mode |
| `workflow` | no | all transitions allowed | Comma-separated `from→to` pairs |
| `lanes` | no | none | Field name to use as the swimlane grouping dimension |
| `card_title` | no | auto-detect | Field name to use as the card heading; set to empty string to show no heading |
| `card_fields` | no | none | Ordered comma-separated list of secondary fields to display below the card heading |
| `card_labels` | no | `true` | Set to `false` to hide the label prefix on secondary card fields |
| `card_limit` | no | `0` (no limit) | Maximum number of cards shown per column; cards beyond this count are hidden behind a "Show more" button |

### `card_title`

```yaml
card_title: summary

Controls which field is rendered as the card heading:

• Absent (default): the first non-_id, non-column field is used automatically
• Set to a field name: that field's value appears as the heading
• Set to empty string (card_title: ): no heading is shown; the card displays only secondary fields

card_fields

card_fields: priority, due, docs

An ordered, comma-separated list of secondary field names to display below the card heading. These appear as labelled rows beneath the title.

Default behaviour: when card_fields is absent the card shows only the heading field. Existing boards with no card_fields key are unaffected.

Unknown names: field names that do not match any defined field are silently ignored at render time. Removing a field from fields: automatically hides it from the card face without a parse error.

Link fields: when a Link field is included in card_fields, its items are rendered as a horizontal list of clickable links on the card face. Vault paths open in a new tab; external URIs open in the browser.

card_labels

card_labels: false

When set to false, the label prefix is omitted from secondary field rows on the card face — only the value is shown. Defaults to true (labels visible). The key is only written to the config when its value is false.

card_limit

card_limit: 5

When set to a positive integer, each column shows at most that many cards. Cards beyond the limit are hidden and a Show more (N) button appears at the bottom of the column. Clicking it reveals all remaining cards without reloading the board. Setting card_limit: 0 or omitting the key disables limiting entirely.

This is particularly useful for boards where the done column accumulates many completed cards over time — the most recently added cards remain visible at a glance, while older history collapses out of the way.

lanes

When set to a field name (must be a Select field), the board renders as a matrix:

• Columns — driven by the status field's options order
• Swimlane rows — driven by the lanes field's options order

Cards with no value for the lanes field appear in an Unassigned pseudo-lane at the bottom. Changing lanes is a view-config change only — no row data is affected.

Field Definitions

Each entry in the fields list is a comma-separated set of key: value pairs on a single line, prefixed with - :

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

Field ordering convention: list title first, then status, then additional fields. The table column order in the data section mirrors the field definition order, and the auto-detected card heading resolves to the first non-_id, non-column field — so placing title first ensures predictable heading resolution without needing an explicit card_title key.

Field Properties

Field Types

Special Field Names

All other fields are secondary — displayed as card metadata when listed in card_fields.

Item Identity

Every card has a stable hidden ID stored in a _id column in the markdown table. The UI never displays this column.

• Generated on card creation: short random alphanumeric string (e.g. 8 characters: x7k2a1b3)
• Preserved through all serialization round-trips
• Survives reordering, drag-and-drop, and field renames
• Used internally for all card operations (move, edit, delete)

Because identity is ID-based and not derived from content, renaming a card's title has no effect on its identity.

Workflow

Defines which status transitions are allowed in the UI:

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

• Comma-separated list of from→to pairs (arrow: →, U+2192)
• If workflow is omitted, all transitions between status options are permitted
• Used to constrain UI choices (e.g. a "Move to" menu only shows valid targets)
• Hand-edits to the raw table bypass workflow validation by nature of being plain text

Board Templates

When creating a new board, a set of predefined templates provides common status option sets. Templates only pre-fill the status field options and workflow — all other fields are added by the user.

Selecting Custom opens a free-form editor for status options and workflow transitions.

Markdown Table

The table appears immediately after the closing --- of the config section.

Structure

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

1. Header row — first column is always _id; remaining columns are field labels in schema definition order
2. Separator row — standard markdown table separator
3. Data rows — one row per card; _id cell contains the card's stable ID

Rules

• Column order in the table must match field definition order (after _id)
• Empty cells are valid (field value = empty string)
• Row order within a status group is the display order
• An empty table (header + separator, no data rows) is valid
• The _id column is always first and is never shown in the rendered board

Escaping

When reading: \| → |, <br> → newline. When writing: | → \|, any newline → <br>.

Parsing Algorithm

1. Extract the raw string between the opening and closing fences of the fancy-kanban block
2. Split on the first --- line to locate the config section start
3. Split on the second --- line to separate config from table
4. Parse config line-by-line: extract title, version, fields, workflow, lanes, card_title, card_fields, card_labels, card_limit
5. For fields, collect lines starting with - and parse each as comma-separated key: value pairs; colors is decoded as pipe-separated name=hex tokens
6. Find table lines in the body (lines starting with |)
7. First table line is the header row — extract column labels; _id is always first
8. Map remaining header labels to field names via case-insensitive label lookup
9. Parse each data row: split on unescaped |, trim cells, unescape \| and <br>
10. First cell of each data row is the card's _id
11. Group cards by status field value, seeding groups in options order

Schema reconciliation (applied after parsing):

• Fields present in schema but missing from a card's data: backfill with the field's default (or empty string)
• Fields present in card data but removed from the schema: preserve as orphaned hidden data (not deleted)

Writing Algorithm

1. Reconstruct the config section from the current schema (preserve original formatting where possible)
2. Generate header row: _id first, then field labels in schema definition order
3. Generate separator row
4. Generate one data row per card: _id first, then field values in schema order, with pipes and newlines escaped
5. Generate a new card _id using a random alphanumeric string if the card has no existing ID
6. Reconstruct the full block: opening fence, config, ---, blank line, table, closing fence

Write-back principle: only the text range of the affected block is patched in the source file — surrounding content is never rewritten.

Minimum Viable Board

```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 |
|-----|-------|--------|

## Compatibility Notes

- Without the plugin, the block renders as a plain code block — all data is still visible as plain text
- The markdown table inside the block is valid markdown and readable in any text editor
- The config section follows YAML conventions familiar to static site generators and note-taking apps
- Removing the plugin leaves all data intact and recoverable

## Deprecated Features

See [docs/deprecations.md](deprecations.md) for the full list of deprecated field types and config keys, their replacements, and planned removal versions.