Markdown & JSON Reference
Full schema reference for board editing
Przegląd
Za każdą tablicą Kanban znajduje się klarotekstowy dokument, który można przeczytać, napisać, kopiować i sprawdzić. Dokument ten składa się z dwóch części: czytelny blok strukturyzowany, zawierający dane z tablicy jako JSON, i wolny blok dla Twoich osobistych notatek.
Zawsze najpierw przeprowadź suchy bieg.
Zanim klikniesz przejmij, użyj przycisku Próbka, aby potwierdzić zmiany. Backend zgłasza błędy i podsumowanie różnic bez zmiany płyty.
Struktura dokumentów
Cały dokument Kanban Markdown składa się z trzech części::
- Przeczytywane przez ludzi nagłówki (nazwa tablicy, notatka generująca)
- Strukturyzowany blok Dane JSON pomiędzy znakami komentarza HTML
- Bezpłatny markdown (powiadomienia, wykresy żółwicy, linki))
# 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 -->Nie usuwaj komentarzy
Znaczniki <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> i <!-- KANBAN:CUSTOM:END --> są niezbędne. Zdejmowanie prowadzi do błędu analitycznego.
Kolumny
Kolumny określają etapy pracy płyty. Od lewej do prawej, przez order-Wartość zwrócona.
"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 }
]| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | Jednoznaczne oznakowanie kolumn (UUID lub dowolny stabilny slug)) |
title | string | Yes | — | Nazwa kolumny wyświetlana w tabeli |
color | string | Yes | #64748b | Kolumnę akcenty kolumny (hex)). Wyświetla się po lewej stronie map |
order | integer | Yes | — | Sterowanie wyświetlaczy oparte na zero (wzrastające, z lewej do prawej)) |
Note
Id identyfikatorów kolumn muszą być jednoznaczne w obrębie tablicy. Wykonywane zadania odnoszą się do kolumn w oparciu o id.
Zadania
Zadania są podstawową jednością pracy. Każde z zadań znajduje się w kolumnie (powyżej columnId) i jest w tej kolumnie po position Sorty.
Minimalne zadanie
{
"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": []
}Kompletne zadanie we wszystkich dziedzinach
{
"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 }
]
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
id | string | Yes | — | Jednoznaczna identyfikacja zadań (UUID lub Stable Slug)) |
columnId | string | Yes | — | ID kolumny, do której należy to zadanie |
position | integer | Yes | — | Sorty 0 w kolumnie |
title | string | Yes | — | Tytuł zadań (1280 znaków)) |
description | string | No | "" | Dłuższy opis zgodny z markdownem |
priority | enum "low""medium""high""critical" | No | medium | Stopień pilności zadania |
tags | string[] | No | [] | Sekwencje znaków dla filtrowania i grupowania |
assigneeIds | string[] | No | [] | Identyfikaty członków osób przypisanych do tej misji |
mentionMemberIds | string[] | No | [] | W tym zadaniu wymienione (przekazane) identyfikaty członków |
estimatePoints | integer|null | No | null | Szacunek w punkcie historii (Fibonacci): 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | ISO 8601 Sekwencja znaków daty: JJJJ-MM-TT |
plannedStartAt | string|null | No | null | ISO 8601 Data/godzina: planowany start |
plannedEndAt | string|null | No | null | ISO 8601 Data/godzina: zakończenie planowane |
timeboxMinutes | integer|null | No | null | Długość sesji spotkań w zakresie timeboxingu |
isCompleted | boolean | No | false | Wyznacza, że zadanie zostało zakończone (dodaj przepływ w interfejsie użytkownika)) |
archivedAt | string|null | No | null | ISO 8601 Data i godzina archiwizacji zadań. Archiwizowane zadania są pominięte w tablicazie |
checklist | object[] | No | [] | Elementy listy kontrolnej podzadania (patrz sekcja checklist)“) |
Elementy listy kontrolnej
Każda z zadań obsługuje płaską listę elementów listy kontrolnej proste podzadania, które mogą być oznaczone jako wykonane indywidualnie bez konieczności tworzenia oddzielnych zadań.
"checklist": [
{ "title": "Design mockup", "isDone": true },
{ "title": "Code review", "isDone": false },
{ "title": "Deploy to prod", "isDone": false }
]| Field | Type | Required | Default | Description |
|---|---|---|---|---|
title | string | Yes | — | Oznaczenie elementu listy kontrolnej (1255 znaków)) |
isDone | boolean | Yes | — | Czy ten punkt jest wycięty |
Sekcja Notice użytkownika“.
Wszystko pomiędzy <!-- KANBAN:CUSTOM:START --> i <!-- KANBAN:CUSTOM:END --> jest to twój blok notatny. Wspiera pełne wykresy Markdown i Mermaid. Treść jest wyświetlana przez maszynę "tablica" ne-pasted wyświetla się tylko w tablicy Preview.
<!-- 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 -->Tip
Wykorzystaj sekcję Userdefined do notatek sprintów, linków zespołowych, wykresów Gantt, wykresów architektonicznych wszystko, co chcesz zobaczyć oprócz danych z tablicy.
Priorytetowe wartości
Połączenie priority Akceptuje dokładnie jedną z czterech wartości. Każdy z nich jest przypisany do określonego koloru znaku w interfejsie użytkownika.:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Mała pilność. Wyświetlone w szczycie/grzew. |
medium | enum value | No | — | Standardowe. Wystosowane w żółtym kolorze. Odrzucanie priorytetu jest standardem. |
high | enum value | No | — | Ważne. W orangi. |
critical | enum value | No | — | Zablokowanie. Wyświetlone w czerwonym/rosym. |
Zadania archiwizacyjne
Aby archiwować zadanie, wprowadź pole archivedAt do sekwencji znaków ISO daty/godziny. Archiwizowane zadania są wykluczone z aktywnego przeglądu, ale pozostają w toku.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
Jeśli ustawisz archivedAt na zero, archiwacja zadania zostanie usunięta. Podsumowanie Diff wykazuje tasksToArchive, gdy używany jest markdown archiwujący aktualnie aktywne zadania na brzegu.
Badanie i diagnoza
Funkcja próbkowa potwierdza odliczenie bez zmian. Z powrotem diffSummary (co by się zmieniło) i diagnostics-Arry powrotnej, która zawiera listę błędów lub ostrzeżeń.
Sukcesyjna reakcja próbna
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Przebieg próbny z błędami
{
"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
}
}| Field | Type | Required | Default | Description |
|---|---|---|---|---|
code | string | Yes | — | Kode błędu czytelnego maszynowo (z. B. nieznany_Spalten_ID) |
message | string | Yes | — | Opis problemu, czytelny dla ludzi |
line | integer | Yes | — | Przybliżony numer linii w dokumencie markdown |
severity | enum "error""warning" | Yes | — | Błąd (zawiera się blokady) lub strzeżenie (wykorzystuje dochody)) |
Blokują błędy Apply
Jeśli w diagnozie znajduje się element o znaczeniu błędu, proces aplikacji odmawia kontynuacji. Ostrzeżenia mają charakter doradczy i nie blokują.
Zalecany przepływ pracy
Wykonaj tę procedurę, gdy pracujesz nad tablicą poprzez markdown:
- Otwórz panel markdown na swojej desce
- Edytuj JSON w Strukturyzowanym bloku dodaj kolumny lub zadania/zmianuj je
- Kliknij dry run, aby zweryfikować bez zmian
- Rozwiązać wszystkie błędy w liście diagnostycznej
- Kliknij Akceptuj, aby dokonać zmian na płytce żywej
- Wykorzystaj Pobierz do lokalnego
.md-Przechowywanie kopii zapasowej
Wskazówka do kontroli wersji
Ponieważ dokument jest czystym tekstem, można go wstawić do repozytorium Git, odróżnić wersje i przywrócić wcześniejszy status tablicy poprzez ponowne zastosowanie starszego zdjęcia.