Schema für Fancy-Kanban-Boards

Eine eigenständige Spezifikation für das markdownbasierte Kanban-Board-Format. Jede App, die Dateien nach diesem Schema liest und schreibt, erzeugt kompatible Boards.

Übersicht

Jedes Board lebt in einem Code-Block mit dem Identifikator fancy-kanban. Das bedeutet:

Ein Board kann überall in einer Notiz eingebettet werden, zusammen mit Text, Links und anderen Inhalten.
Eine Notiz kann null, ein oder mehrere Boards enthalten.
Eine Datei, die nur aus einem einzigen Board-Block besteht, ist eine eigenständige Board-Datei.
Ohne installiertes Plugin wird der Block als unformatierter Code-Block dargestellt – der Rohtext bleibt vollständig lesbar.

Der Block enthält zwei durch --- getrennte Abschnitte:

Einen Konfigurationsabschnitt (YAML-ähnlich), der Felder, Workflow und Ansichtsoptionen definiert.
Eine Markdown-Tabelle, die die Datenzeilen enthält.

Vollständiges Beispiel

```fancy-kanban
---
title: Mein Board
fields:
  - name: title,       type: Text,     label: Titel
  - name: status,      type: Select,   options: inbox|doing|done, label: Status, default: inbox
  - name: responsible, type: Text,     label: Verantwortlich
  - name: start_date,  type: Date,     label: Startdatum
  - name: notes,       type: Textarea, label: Notizen
  - name: effort,      type: Number,   label: Aufwand
  - name: docs,        type: Link,     label: Dokumente
  - 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    | Titel          | Status | Verantwortlich | Startdatum | Notizen                      | Aufwand | Dokumente            | Team     |
|--------|----------------|--------|----------------|------------|------------------------------|---------|----------------------|----------|
| x7k2a1 | Login-Bug fix  | inbox  | Alice          | 2026-01-15 | Erfordert Untersuchung       | 3       |                      | backend  |
| m3p9b2 | Auth umbauen   | doing  | Bob            |            | Mehrzeiliger\<br\>Inhalt hier | 5       | design.md            | backend  |
| q1r4c3 | CI einrichten  | done   |                | 2026-01-01 |                              | 1       | setup.md\|guide.md   | frontend |
```

Blockstruktur

Der Code-Block enthält genau zwei durch eine ----Zeile getrennte Abschnitte:

```fancy-kanban
---
{Konfiguration}
---
{Markdown-Tabelle}


Alles vor der ersten `---` wird ignoriert (reserviert für zukünftige Verwendung). Alles zwischen den beiden `---`-Zeilen ist die Konfiguration. Alles nach der zweiten `---` ist die Tabelle.

## Konfigurationsabschnitt

YAML-ähnliche Schlüssel-Wert-Paare. Zeilenweise analysiert.

### Schlüssel

| Schlüssel | Erforderlich | Standard | Beschreibung |
|-----------|--------------|----------|--------------|
| `title` | ja | — | Menschenlesbarer Board-Name |
| `fields` | ja | — | Liste der Felddefinitionen (siehe unten) |
| `version` | nein | `1` | Formatversion, die vom Plugin geschrieben wird; Boards mit einer höheren Version als vom aktuellen Plugin unterstützt, werden im schreibgeschützten Modus geöffnet |
| `workflow` | nein | Alle Übergänge erlaubt | Kommagetrennte `von→zu`-Paare |
| `lanes` | nein | Keine | Feldname, der für die Swimlane-Gruppierung verwendet werden soll |
| `card_title` | nein | Automatische Erkennung | Feldname, der als Kartenüberschrift verwendet werden soll; auf leeren String setzen, um keine Überschrift anzuzeigen |
| `card_fields` | nein | Keine | Geordnete, kommagetrennte Liste von sekundären Feldern, die unter der Kartenüberschrift angezeigt werden sollen |
| `card_labels` | nein | `true` | Auf `false` setzen, um die Label-Präfixe auf sekundären Kartenfeldern auszublenden |
| `card_limit` | nein | `0` (kein Limit) | Maximale Anzahl von Karten, die pro Spalte angezeigt werden; Karten über dieser Anzahl werden hinter einem „Mehr anzeigen“-Button versteckt |

### `card_title`

```yaml
card_title: zusammenfassung

Steuert, welches Feld als Kartenüberschrift dargestellt wird:

Fehlt (Standard): Das erste Nicht-_id-, Nicht-Spaltenfeld wird automatisch verwendet.
Auf einen Feldnamen gesetzt: Der Wert dieses Feldes erscheint als Überschrift.
Auf leeren String gesetzt (card_title: ): Es wird keine Überschrift angezeigt; die Karte zeigt nur sekundäre Felder.

`card_fields`

card_fields: prioritaet, fällig, docs

Eine geordnete, kommagetrennte Liste von sekundären Feldnamen, die unter der Kartenüberschrift angezeigt werden sollen. Diese erscheinen als beschriftete Zeilen unter dem Titel.

Standardverhalten: Wenn card_fields fehlt, zeigt die Karte nur das Überschriftfeld. Vorhandene Boards ohne card_fields-Schlüssel sind nicht betroffen.

Unbekannte Namen: Feldnamen, die zu keinem definierten Feld passen, werden während der Darstellung stillschweigend ignoriert. Das Entfernen eines Feldes aus fields: blendet es automatisch von der Kartenoberfläche aus, ohne einen Analysefehler zu verursachen.

Link-Felder: Wenn ein Link-Feld in card_fields enthalten ist, werden seine Elemente als horizontale Liste von klickbaren Links auf der Kartenoberfläche dargestellt. Vault-Pfade werden in einem neuen Tab geöffnet; externe URIs werden im Browser geöffnet.

`card_labels`

card_labels: false

Wenn auf false gesetzt, wird das Label-Präfix bei sekundären Feldzeilen auf der Kartenoberfläche weggelassen – nur der Wert wird angezeigt. Standard ist true (Labels sichtbar). Der Schlüssel wird nur in die Konfiguration geschrieben, wenn sein Wert false ist.

`card_limit`

card_limit: 5

Wenn auf eine positive Ganzzahl gesetzt, zeigt jede Spalte höchstens so viele Karten an. Karten über dem Limit werden ausgeblendet und ein Button Mehr anzeigen (N) erscheint am unteren Ende der Spalte. Ein Klick darauf zeigt alle verbleibenden Karten an, ohne das Board neu zu laden. Das Setzen von card_limit: 0 oder das Weglassen des Schlüssels deaktiviert die Begrenzung vollständig.

Dies ist besonders nützlich für Boards, bei denen die erledigt-Spalte im Laufe der Zeit viele abgeschlossene Karten ansammelt – die zuletzt hinzugefügten Karten bleiben auf einen Blick sichtbar, während ältere Geschichte aus dem Weg geräumt wird.

`lanes`

Wenn auf einen Feldnamen gesetzt (muss ein Select-Feld sein), wird das Board als Matrix dargestellt:

Spalten – gesteuert durch die Reihenfolge der options des Statusfeldes.
Swimlane-Zeilen – gesteuert durch die Reihenfolge der options des lanes-Feldes.

Karten ohne Wert für das Lanes-Feld erscheinen in einer Nicht zugewiesen-Pseudo-Lane am unteren Ende. Das Ändern von lanes ist nur eine Ansichtskonfigurationsänderung – keine Zeilendaten werden beeinflusst.

Felddefinitionen

Jeder Eintrag in der fields-Liste ist eine kommagetrennte Menge von Schlüssel: Wert-Paaren in einer einzigen Zeile, prefixiert mit - :

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

Feldreihenfolge-Konvention: title zuerst, dann status, dann zusätzliche Felder. Die Tabellenspaltenreihenfolge im Datenabschnitt spiegelt die Felddefinitionsreihenfolge wider, und die automatisch erkannte Kartenüberschrift ergibt sich aus dem ersten Nicht-_id-, Nicht-Spaltenfeld – daher stellt das Platzieren von title an erster Stelle eine vorhersagbare Überschriftsauflösung sicher, ohne dass ein expliziter card_title-Schlüssel erforderlich ist.

Feldeigenschaften

Eigenschaft	Erforderlich	Beschreibung
`name`	ja	Interner Identifikator. Kleinbuchstaben, Unterstriche für Leerzeichen.
`type`	ja	Einer von: `Text`, `Textarea`, `Date`, `Number`, `Select`, `Link`
`label`	ja	Menschenlesbarer Spaltentitel. Muss exakt mit dem Markdown-Tabellenkopf übereinstimmen.
`options`	Nur bei Select	Durch Pipe getrennte (`
`colors`	Select, optional	Durch Pipe getrennte `Name=hex`-Paare, die jedem Wert eine Hintergrundfarbe zuweisen (z. B. `Hoch=#e74c3c
`default`	nein	Standardwert für neue Karten

Feldtypen

Typ	Speicherformat	Beschreibung
`Text`	Einfacher String	Einzeiliger Text
`Textarea`	String mit `<br>` für Zeilenumbrüche	Mehrzeiliger Text
`Date`	`YYYY-MM-DD`	Kalenderdatum
`Number`	Ganzzahl oder Dezimalzahl als String	Numerischer Wert
`Select`	Einer der `options`-Werte	Eingeschränkte Auswahl; Optionen können über die `colors`-Eigenschaft Hex-Farben tragen
`Link`	`<br>`-getrennte Liste von Pfaden oder URIs	Vault-root-relative Pfade (`notes/doc.pdf`) oder externe URIs (`https://…`, `ftp://…`, `mailto:…`)

Spezielle Feldnamen

Name	Rolle
`title`	Primäres Anzeigefeld. Sollte als erstes in `fields:` aufgeführt werden. Wird als automatisch erkannte Kartenüberschrift verwendet, wenn `card_title` nicht gesetzt ist.
`status`	Erforderlich. Kanban-Spaltenfeld. Muss `type: Select` sein. Karten werden nach diesem Wert in Spalten gruppiert. Die Spaltenreihenfolge folgt der `options`-Reihenfolge.

Alle anderen Felder sind sekundär – werden als Kartenmetadaten angezeigt, wenn sie in card_fields aufgeführt sind.

Elementidentität

Jede Karte hat eine stabile versteckte ID, die in einer _id-Spalte in der Markdown-Tabelle gespeichert ist. Die Benutzeroberfläche zeigt diese Spalte nie an.

Wird bei der Kartenerstellung generiert: kurzer zufälliger alphanumerischer String (z. B. 8 Zeichen: x7k2a1b3)
Wird durch alle Serialisierungszyklen hindurch beibehalten
Überlebt Neuanordnungen, Drag-and-Drop und Feldumbenennungen
Wird intern für alle Kartenoperationen (Verschieben, Bearbeiten, Löschen) verwendet

Da die Identität ID-basiert und nicht aus dem Inhalt abgeleitet ist, hat das Umbenennen des Kartentitels keine Auswirkung auf ihre Identität.

Workflow

Definiert, welche Statusübergänge in der Benutzeroberfläche erlaubt sind:

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

Kommagetrennte Liste von von→zu-Paaren (Pfeil: →, U+2192)
Wenn workflow fehlt, sind alle Übergänge zwischen Statusoptionen erlaubt
Wird verwendet, um UI-Auswahlmöglichkeiten einzuschränken (z. B. zeigt ein „Verschieben nach“-Menü nur gültige Ziele an)
Manuelle Bearbeitungen der Rohtabelle umgehen die Workflow-Validierung, da sie reiner Text sind

Board-Vorlagen

Beim Erstellen eines neuen Boards bietet eine Reihe vordefinierter Vorlagen gebräuchliche Sätze von status-Optionen. Vorlagen füllen nur die status-Feldoptionen und den workflow vor – alle anderen Felder werden vom Benutzer hinzugefügt.

Vorlage	Status-Optionen	Standard-Workflow
Basis	`inbox \| doing \| done`	Alle Übergänge
Software	`backlog \| todo \| in-progress \| review \| done`	Vorwärts + ein Schritt zurück
Inhalt	`idea \| draft \| review \| published`	Nur vorwärts
Projekt	`planning \| active \| blocked \| complete`	Alle außer → planning
Benutzerdefiniert	Benutzerdefiniert	Benutzerdefiniert

Die Auswahl von Benutzerdefiniert öffnet einen freien Editor für Statusoptionen und Workflow-Übergänge.

Markdown-Tabelle

Die Tabelle erscheint unmittelbar nach der schließenden --- des Konfigurationsabschnitts.

Struktur

| _id    | Kopf1 | Kopf2 |
|--------|-------|-------|
| abc123 | wert  | wert  |

Kopfzeile – erste Spalte ist immer _id; die restlichen Spalten sind Feldbezeichnungen in der Reihenfolge der Schemadefinition
Trennzeile – standardmäßige Markdown-Tabellentrennzeile
Datenzeilen – eine Zeile pro Karte; die _id-Zelle enthält die stabile ID der Karte

Regeln

Die Spaltenreihenfolge in der Tabelle muss der Felddefinitionsreihenfolge entsprechen (nach _id)
Leere Zellen sind gültig (Feldwert = leerer String)
Die Zeilenreihenfolge innerhalb einer Statusgruppe ist die Anzeigereihenfolge
Eine leere Tabelle (Kopfzeile + Trennzeile, keine Datenzeilen) ist gültig
Die _id-Spalte ist immer die erste und wird im gerenderten Board nie angezeigt

Escaping

Zeichen im Wert	Escaped als
`\|` (Pipe)	`\|` (Backslash-Pipe)
Zeilenumbruch	`<br>`
Wagenrücklauf	`<br>`

Beim Lesen: \| → |, <br> → Zeilenumbruch. Beim Schreiben: | → \|, jeder Zeilenumbruch → <br>.

Parsing-Algorithmus

Extrahiere den rohen String zwischen der öffnenden und schließenden Code-Block-Markierung des fancy-kanban-Blocks
Teile an der ersten ----Zeile, um den Beginn des Konfigurationsabschnitts zu lokalisieren
Teile an der zweiten ----Zeile, um die Konfiguration von der Tabelle zu trennen
Analysiere die Konfiguration zeilenweise: extrahiere title, version, fields, workflow, lanes, card_title, card_fields, card_labels, card_limit
Für fields: Sammle Zeilen, die mit - beginnen, und analysiere jede als kommagetrennte Schlüssel: Wert-Paare; colors wird als pipe-getrennte Name=hex-Token dekodiert
Finde Tabellenzeilen im Text (Zeilen, die mit | beginnen)
Die erste Tabellenzeile ist die Kopfzeile – extrahiere Spaltenbezeichnungen; _id ist immer die erste
Ordne die verbleibenden Kopfzeilen-Bezeichnungen Feldnamen durch eine Groß-/Kleinschreibung-unabhängige Label-Suche zu
Analysiere jede Datenzeile: Teile an nicht escapeden |, trimme Zellen, entscappe \| und <br>
Die erste Zelle jeder Datenzeile ist die _id der Karte
Gruppiere Karten nach dem Wert des status-Feldes, erstelle Gruppen in der options-Reihenfolge

Schema-Abgleich (nach dem Parsen angewendet):

Felder, die im Schema vorhanden sind, aber in den Kartendaten fehlen: fülle mit dem default-Wert des Feldes (oder leerem String) auf
Felder, die in den Kartendaten vorhanden sind, aber aus dem Schema entfernt wurden: behalte als verwaiste versteckte Daten (nicht gelöscht)

Schreib-Algorithmus

Rekonstruiere den Konfigurationsabschnitt aus dem aktuellen Schema (bewahre die ursprüngliche Formatierung nach Möglichkeit)
Generiere die Kopfzeile: _id zuerst, dann Feldbezeichnungen in der Reihenfolge der Schemadefinition
Generiere die Trennzeile
Generiere eine Datenzeile pro Karte: _id zuerst, dann Feldwerte in Schema-Reihenfolge, mit escapeden Pipes und Zeilenumbrüchen
Generiere eine neue Karten-_id mit einem zufälligen alphanumerischen String, wenn die Karte keine vorhandene ID hat
Rekonstruiere den vollständigen Block: öffnende Code-Block-Markierung, Konfiguration, ---, Leerzeile, Tabelle, schließende Code-Block-Markierung

Rückschreib-Prinzip: Nur der Textbereich des betroffenen Blocks wird in der Quelldatei gepatcht – umgebender Inhalt wird nie neu geschrieben.

Minimales funktionsfähiges Board

```fancy-kanban
---
title: Mein Board
fields:
  - name: title, type: Text, label: Titel
  - 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 | Titel | Status |
|-----|-------|--------|


## Kompatibilitätshinweise

- Ohne das Plugin wird der Block als einfacher Code-Block dargestellt – alle Daten sind weiterhin als Klartext sichtbar
- Die Markdown-Tabelle innerhalb des Blocks ist gültiges Markdown und in jedem Texteditor lesbar
- Der Konfigurationsabschnitt folgt YAML-Konventionen, die von statischen Site-Generatoren und Notiz-Apps bekannt sind
- Das Entfernen des Plugins hinterlässt alle Daten intakt und wiederherstellbar

## Veraltete Funktionen

Siehe [docs/deprecations.md](deprecations.md) für die Liste der veralteten Funktionen und deren Migrationspfade.

robertoallende/fancy-kanban

Was ist fancy-kanban?

In Ihrer bevorzugten KI fragen

Dokumentation