Kanban Studio›Markdown & JSON Reference

📝

Markdown & JSON Reference

Full schema reference for board editing

Übersicht

Hinter jedem Kanban-Board steht ein Klartext-Markdown-Dokument, das Sie lesen, schreiben, kopieren und einer Versionskontrolle unterziehen können. Das Dokument besteht aus zwei Abschnitten: einem maschinenlesbaren strukturierten Block, der die Board-Daten als JSON enthält, und einem freien benutzerdefinierten Block für Ihre persönlichen Notizen.

Schema v1JSON + MarkdownTrockenlaufsicher

💡

Führen Sie immer zuerst einen Trockenlauf durch

Bevor Sie auf „Übernehmen“ klicken, verwenden Sie die Schaltfläche „Probelauf“, um Ihre Änderungen zu validieren. Das Backend meldet Fehler und eine Diff-Zusammenfassung, ohne Ihr Board zu ändern.

Dokumentstruktur

Ein vollständiges Kanban-Markdown-Dokument besteht aus drei Teilen:

Eine für Menschen lesbare Kopfzeile (Boardtitel, Generierungsnotiz)
Der Strukturierte Block – JSON-Daten zwischen HTML-Kommentarmarkierungen
Der Benutzerdefinierte Block – kostenloser Markdown (Notizen, Mermaid-Diagramme, Links)

board.md

# My Project Board

Generated by Kanban Markdown schema v1.

<!-- KANBAN:STRUCTURED:START -->
```kanban-structured
{
  "version": 1,
  "board": {
    "id": "board-abc123",
    "title": "My Project Board"
  },
  "columns": [
    { "id": "col-1", "title": "Backlog",     "color": "#64748b", "order": 0 },
    { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
    { "id": "col-3", "title": "Done",        "color": "#10b981", "order": 2 }
  ],
  "tasks": [
    {
      "id": "task-1",
      "columnId": "col-2",
      "position": 0,
      "title": "Build authentication flow",
      "description": "Implement JWT login, register, and token refresh.",
      "priority": "high",
      "tags": ["backend", "security"],
      "assigneeIds": ["member-uuid-1"],
      "mentionMemberIds": ["member-uuid-2"],
      "estimatePoints": 5,
      "dueDate": "2025-03-15",
      "plannedStartAt": "2025-03-10",
      "plannedEndAt": "2025-03-15",
      "timeboxMinutes": 90,
      "isCompleted": false,
      "archivedAt": null,
      "checklist": [
        { "title": "Design DB schema",   "isDone": true  },
        { "title": "Write unit tests",   "isDone": false },
        { "title": "Deploy to staging",  "isDone": false }
      ]
    }
  ]
}
```
<!-- KANBAN:STRUCTURED:END -->

<!-- KANBAN:CUSTOM:START -->
## Team Notes

- Sprint ends Friday
- Backend review at 3 PM

```mermaid
flowchart LR
  A[Backlog] --> B[In Progress] --> C[Done]
```
<!-- KANBAN:CUSTOM:END -->

Vollständiges Board-Dokument mit Anmerkungen zu allen Abschnitten

⚠️

Entfernen Sie nicht die Kommentarmarkierungen

Die Marker , ,  und  sind erforderlich. Das Entfernen führt zu einem Analysefehler.

Spalten

Spalten definieren die Arbeitsablaufphasen Ihres Boards. Sie werden von links nach rechts durch ihren order-Wert gerendert.

JSON

"columns": [
  { "id": "col-1", "title": "To Do",       "color": "#64748b", "order": 0 },
  { "id": "col-2", "title": "In Progress", "color": "#6366f1", "order": 1 },
  { "id": "col-3", "title": "Review",      "color": "#f59e0b", "order": 2 },
  { "id": "col-4", "title": "Done",        "color": "#10b981", "order": 3 }
]

Beispiel: vier Spalten mit unterschiedlichen Farben

Field	Type	Required	Default	Description
`id`	string	Yes	—	Eindeutiger Spaltenbezeichner (UUID oder ein beliebiger stabiler Slug)
`title`	string	Yes	—	Spaltenüberschrift auf der Tafel angezeigt
`color`	string	Yes	`#64748b`	Spaltenakzentfarbe (hex). Wird als linker Rand auf Karten angezeigt
`order`	integer	Yes	—	Nullbasierte Anzeigereihenfolge (aufsteigend, von links nach rechts)

ℹ️

Note

Spalten-IDs müssen innerhalb des Boards eindeutig sein. Aufgaben verweisen auf Spalten anhand dieses id.

Aufgaben

Aufgaben sind die Kerneinheit der Arbeit. Jede Aufgabe befindet sich in einer Spalte (über columnId) und ist innerhalb dieser Spalte nach position sortiert.

Minimale Aufgabe

JSON

{
  "id": "task-abc",
  "columnId": "col-1",
  "position": 0,
  "title": "Write release notes",
  "description": "",
  "priority": "medium",
  "tags": [],
  "assigneeIds": [],
  "mentionMemberIds": [],
  "estimatePoints": null,
  "dueDate": null,
  "plannedStartAt": null,
  "plannedEndAt": null,
  "timeboxMinutes": null,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": []
}

Nur Pflichtfelder ausgefüllt – alle optionalen Felder sind null/leer

Vollständige Aufgabe mit allen Feldern

JSON

{
  "id": "task-xyz",
  "columnId": "col-2",
  "position": 0,
  "title": "Redesign checkout page",
  "description": "Full UX overhaul based on user research findings.",
  "priority": "critical",
  "tags": ["ux", "frontend", "q1-goal"],
  "assigneeIds": ["member-alice", "member-bob"],
  "mentionMemberIds": ["member-pm"],
  "estimatePoints": 8,
  "dueDate": "2025-04-01",
  "plannedStartAt": "2025-03-20",
  "plannedEndAt": "2025-04-01",
  "timeboxMinutes": 120,
  "isCompleted": false,
  "archivedAt": null,
  "checklist": [
    { "title": "User interviews",       "isDone": true  },
    { "title": "Wireframes approved",   "isDone": true  },
    { "title": "Implement components",  "isDone": false },
    { "title": "A/B test live",         "isDone": false }
  ]
}

Produktionsbeispiel mit Priorität, Tags, Beauftragten, Checkliste, Zeiterfassung

Field	Type	Required	Default	Description
`id`	string	Yes	—	Eindeutige Aufgabenkennung (UUID oder Stable Slug)
`columnId`	string	Yes	—	ID der Spalte, zu der diese Aufgabe gehört
`position`	integer	Yes	—	Nullbasierte Sortierreihenfolge innerhalb der Spalte
`title`	string	Yes	—	Aufgabentitel (1–280 Zeichen)
`description`	string	No	`""`	Markdown-kompatible längere Beschreibung
`priority`	enum "low""medium""high""critical"	No	`medium`	Dringlichkeitsstufe der Aufgabe
`tags`	string[]	No	`[]`	Freiform-Beschriftungszeichenfolgen zum Filtern und Gruppieren
`assigneeIds`	string[]	No	`[]`	Mitglieds-IDs von Personen, die dieser Aufgabe zugewiesen sind
`mentionMemberIds`	string[]	No	`[]`	In dieser Aufgabe erwähnte (mitgeteilte) Mitglieds-IDs
`estimatePoints`	integer\|null	No	`null`	Story-Point-Schätzung (Fibonacci: 1, 2, 3, 5, 8, 13…)
`dueDate`	string\|null	No	`null`	ISO 8601-Datumszeichenfolge: JJJJ-MM-TT
`plannedStartAt`	string\|null	No	`null`	ISO 8601 Datum/Uhrzeit: geplanter Start
`plannedEndAt`	string\|null	No	`null`	ISO 8601 Datum/Uhrzeit: geplantes Ende
`timeboxMinutes`	integer\|null	No	`null`	Länge der Fokussitzung für Timeboxing
`isCompleted`	boolean	No	`false`	Markiert die Aufgabe als erledigt (fügt Durchstreichung in der Benutzeroberfläche hinzu)
`archivedAt`	string\|null	No	`null`	ISO 8601-Datum und Uhrzeit der Archivierung der Aufgabe. Archivierte Aufgaben werden im Board ausgeblendet
`checklist`	object[]	No	`[]`	Elemente der Unteraufgaben-Checkliste (siehe Abschnitt „Checkliste“)

Checklistenelemente

Jede Aufgabe unterstützt eine flache Liste von Checklistenelementen – einfache Unteraufgaben, die einzeln als erledigt markiert werden können, ohne dass separate Aufgaben erstellt werden müssen.

JSON

"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]

Drei Checklistenpunkte: der erste erledigt, zwei übrig

Field	Type	Required	Default	Description
`title`	string	Yes	—	Beschriftung des Checklistenelements (1–255 Zeichen)
`isDone`	boolean	Yes	—	Ob dieser Punkt abgehakt ist

Abschnitt „Benutzerdefinierte Notizen“.

Alles zwischen  und  ist Ihr Notizblock. Es unterstützt vollständige Markdown- und Mermaid-Diagramme. Der Inhalt wird von der Board-Engine nie geparst – er wird nur auf der Registerkarte „Vorschau“ angezeigt.

Markdown

<!-- KANBAN:CUSTOM:START -->
## Sprint Notes

- Daily standup at 10:00 AM
- Backend API freeze on Friday

```mermaid
gantt
  title Sprint 12
  section Tasks
  Auth flow     :done, 2025-03-10, 3d
  Dashboard UI  :active, 2025-03-13, 4d
  API docs      :2025-03-17, 2d
```

> Reminder: update JIRA tickets before end of day.
<!-- KANBAN:CUSTOM:END -->

Notizen mit einem Meerjungfrau-Gantt-Diagramm

💡

Tip

Verwenden Sie den Abschnitt „Benutzerdefiniert“ für Sprintnotizen, Teamlinks, Gantt-Diagramme, Architekturdiagramme – alles, was Sie neben Ihren Board-Daten sehen möchten.

Prioritätswerte

Das Feld priority akzeptiert genau einen von vier Werten. Jedes wird einer bestimmten Abzeichenfarbe in der Benutzeroberfläche zugeordnet:

Field	Type	Required	Default	Description
`low`	enum value	No	—	Geringe Dringlichkeit. Abgebildet in Schiefer/Grau.
`medium`	enum value	No	—	Standard. Dargestellt in Bernstein/Gelb. Das Weglassen der Priorität ist die Standardeinstellung.
`high`	enum value	No	—	Wichtig. In Orange dargestellt.
`critical`	enum value	No	—	Blockieren. Abgebildet in Rot/Rosa.

Archivierungsaufgaben

Um eine Aufgabe zu archivieren, setzen Sie ihr Feld archivedAt auf eine ISO-Datums-/Uhrzeitzeichenfolge. Archivierte Aufgaben werden von der aktiven Board-Ansicht ausgeschlossen, bleiben aber im Verlauf erhalten.

JSON

{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}

Archivierte Aufgabe – vom Board ausgeblendet, im Snapshot erhalten

ℹ️

Note

Wenn Sie archivedAt auf null setzen, wird die Archivierung der Aufgabe aufgehoben. Die Diff-Zusammenfassung zeigt „tasksToArchive“ an, wenn ein Markdown-Snapshot angewendet wird, der derzeit aktive Aufgaben auf dem Board archiviert.

Probelauf und Diagnose

Die Probelauffunktion validiert Ihren Abschlag, ohne Änderungen vorzunehmen. Das Backend gibt ein diffSummary (was sich ändern würde) und ein diagnostics-Array zurück, das alle Fehler oder Warnungen auflistet.

Erfolgreiche Probelaufreaktion

JSON

{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}

ok: true bedeutet, dass der Abschlag gültig und sicher anzuwenden ist

Probelauf mit Fehlern

JSON

{
  "ok": false,
  "dryRun": true,
  "diagnostics": [
    {
      "code": "unknown_column_id",
      "message": "Task 'task-xyz' references unknown column 'col-999'.",
      "line": 42,
      "severity": "error"
    },
    {
      "code": "duplicate_task_id",
      "message": "Task ID 'task-abc' is used more than once.",
      "line": 67,
      "severity": "error"
    }
  ],
  "diffSummary": {
    "columnsCreated": 0,
    "columnsTouched": 0,
    "tasksCreated": 0,
    "tasksTouched": 0,
    "tasksToArchive": 0
  }
}

ok: false – Fehler vor der Anwendung beheben

Field	Type	Required	Default	Description
`code`	string	Yes	—	Maschinenlesbarer Fehlercode (z. B. unbekannte_Spalten_ID)
`message`	string	Yes	—	Für Menschen lesbare Beschreibung des Problems
`line`	integer	Yes	—	Ungefähre Zeilennummer im Markdown-Dokument
`severity`	enum "error""warning"	Yes	—	Entweder „Fehler“ (Sperren gelten) oder „Warnung“ (Erlöse anwenden)

🚫

Fehler blockieren Apply

Wenn die Diagnose ein Element mit dem Schweregrad „Fehler“ enthält, verweigert der Apply-Vorgang die Fortsetzung. Warnungen haben beratenden Charakter und blockieren nicht.

Empfohlener Workflow

Befolgen Sie diesen Ablauf, wenn Sie das Board über Markdown bearbeiten:

Öffnen Sie das Markdown-Panel auf Ihrem Board
Bearbeiten Sie den JSON im Strukturierten Block – fügen Sie Spalten oder Aufgaben hinzu/ändern Sie sie
Klicken Sie auf Trockenlauf, um zu validieren, ohne etwas zu ändern
Beheben Sie alle in der Diagnoseliste angezeigten Fehler
Klicken Sie auf Übernehmen, um Änderungen am Live-Board zu übernehmen
Verwenden Sie Herunterladen, um ein lokales .md-Backup zu speichern

💡

Tipp zur Versionskontrolle

Da es sich bei dem Dokument um reinen Text handelt, können Sie es in ein Git-Repository einfügen, Versionen unterscheiden und frühere Board-Status wiederherstellen, indem Sie einen älteren Snapshot erneut anwenden.