Markdown & JSON Reference
Full schema reference for board editing
Panoramica
Ogni lavagna Kanban è supportata da un documento Markdown in testo semplice che puoi leggere, scrivere, copiare e controllare la versione. Il documento ha due sezioni: un blocco Strutturato leggibile dalla macchina che contiene i dati della scheda come JSON e un blocco Personalizzato in formato libero per le tue note personali.
Prima eseguire sempre un test a secco
Prima di fare clic su Applica, utilizzare il pulsante Prova per convalidare le modifiche. Il backend riporterà gli errori e un riepilogo delle differenze senza modificare la scheda.
Struttura del documento
Un documento Kanban Markdown completo è composto da tre parti:
- Un'intestazione leggibile dall'uomo (titolo della scheda, nota di generazione)
- Il blocco strutturato: dati JSON tra marcatori di commenti HTML
- Il Blocco personalizzato: Markdown gratuito (note, diagrammi delle sirene, collegamenti)
# 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 -->Non rimuovere i marcatori di commento
I marcatori <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> sono obbligatori. La loro rimozione provoca un errore di analisi.
Colonne
Le colonne definiscono le fasi del flusso di lavoro della tua scheda. Sono visualizzati da sinistra a destra in base al loro valore order.
"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 | — | Identificatore univoco della colonna (UUID o qualsiasi slug stabile) |
title | string | Yes | — | Intestazione della colonna mostrata sulla lavagna |
color | string | Yes | #64748b | Colore in risalto della colonna (esadecimale). Mostrato come bordo sinistro sulle carte |
order | integer | Yes | — | Ordine di visualizzazione in base zero (ascendente, da sinistra a destra) |
Note
Gli ID delle colonne devono essere univoci all'interno della scheda. Le attività fanno riferimento alle colonne tramite questo id.
Compiti
I compiti sono l’unità centrale del lavoro. Ogni attività si trova all'interno di una colonna (tramite columnId) ed è ordinata per position all'interno di quella colonna.
Compito minimo
{
"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": []
}Attività completa con tutti i campi
{
"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 | — | Identificatore univoco dell'attività (UUID o slug stabile) |
columnId | string | Yes | — | ID della colonna a cui appartiene questa attività |
position | integer | Yes | — | Ordinamento in base zero all'interno della colonna |
title | string | Yes | — | Titolo dell'attività (1–280 caratteri) |
description | string | No | "" | Descrizione più lunga compatibile con Markdown |
priority | enum "low""medium""high""critical" | No | medium | Livello di urgenza dell'attività |
tags | string[] | No | [] | Stringhe di etichette in formato libero per filtrare e raggruppare |
assigneeIds | string[] | No | [] | ID membro delle persone assegnate a questa attività |
mentionMemberIds | string[] | No | [] | ID membro menzionati (notificati) in questa attività |
estimatePoints | integer|null | No | null | Stima del punto della storia (Fibonacci: 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | Stringa della data ISO 8601: AAAA-MM-GG |
plannedStartAt | string|null | No | null | Data e ora ISO 8601: inizio pianificato |
plannedEndAt | string|null | No | null | Data e ora ISO 8601: fine pianificata |
timeboxMinutes | integer|null | No | null | Durata della sessione focus per il timeboxing |
isCompleted | boolean | No | false | Contrassegna l'attività come completata (aggiunge barrato nell'interfaccia utente) |
archivedAt | string|null | No | null | Data e ora ISO 8601 in cui l'attività è stata archiviata. Le attività archiviate sono nascoste dalla bacheca |
checklist | object[] | No | [] | Elementi dell'elenco di controllo delle attività secondarie (vedere la sezione Elenco di controllo) |
Elementi della lista di controllo
Ogni attività supporta un elenco semplice di elementi della lista di controllo: attività secondarie leggere che possono essere contrassegnate individualmente come completate senza creare attività separate.
"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 | — | Etichetta dell'elemento dell'elenco di controllo (1–255 caratteri) |
isDone | boolean | Yes | — | Se questo elemento è selezionato |
Sezione note personalizzate
Tutto tra <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> è il tuo blocco appunti. Supporta i diagrammi Markdown e Sirena completi. Il contenuto non viene mai analizzato dal motore della scheda: viene mostrato solo nella scheda Anteprima.
<!-- 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
Utilizza la sezione Personalizzata per note sullo sprint, collegamenti al team, diagrammi di Gantt, diagrammi di architettura: tutto ciò che desideri sia visibile insieme ai dati della scheda.
Valori prioritari
Il campo priority accetta esattamente uno dei quattro valori. Ciascuno è associato a un colore distintivo distinto nell'interfaccia utente:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Bassa urgenza. Mostrato in ardesia/grigio. |
medium | enum value | No | — | Predefinito. Mostrato in ambra/giallo. Per impostazione predefinita, l'omissione della priorità è questa. |
high | enum value | No | — | Importante. Mostrato in arancione. |
critical | enum value | No | — | Blocco. Mostrato in rosso/rosa. |
Attività di archiviazione
Per archiviare un'attività, imposta il suo campo archivedAt su una stringa data/ora ISO. Le attività archiviate vengono escluse dalla visualizzazione attiva della bacheca ma conservate nella cronologia.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
L'impostazione di archivedAt su null annulla l'archiviazione dell'attività. Il riepilogo delle differenze mostrerà taskToArchive quando si applica un'istantanea markdown che archivia le attività attualmente attive sulla scheda.
Prova di funzionamento e diagnostica
La funzione di prova convalida il ribasso senza applicare modifiche. Il backend restituisce un diffSummary (cosa cambierebbe) e un array diagnostics che elenca eventuali errori o avvisi.
Risposta di prova riuscita
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Prova con errori
{
"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 | — | Codice di errore leggibile dalla macchina (ad es. Unknown_column_id) |
message | string | Yes | — | Descrizione leggibile del problema |
line | integer | Yes | — | Numero di riga approssimativo nel documento di ribasso |
severity | enum "error""warning" | Yes | — | O "errore" (si applicano i blocchi) o "avviso" (si applicano i proventi) |
Blocco errori Applica
Se la diagnostica contiene elementi con gravità: "errore", l'operazione di applicazione rifiuterà di procedere. Gli avvisi sono consultivi e non bloccano.
Flusso di lavoro consigliato
Segui questo flusso quando modifichi la scheda tramite Markdown:
- Apri il pannello Markdown sulla tua scheda
- Modifica il JSON nel Blocco strutturato: aggiungi/modifica colonne o attività
- Fare clic su Esecuzione di prova per convalidare senza modificare nulla
- Correggere eventuali errori visualizzati nell'elenco di diagnostica
- Fai clic su Applica per applicare le modifiche alla bacheca live
- Utilizza Download per salvare un backup locale
.md.
Suggerimento per il controllo della versione
Poiché il documento è di testo semplice, puoi incollarlo in un repository Git, versioni diff e ripristinare gli stati precedenti della scheda riapplicando uno snapshot precedente.