Markdown & JSON Reference
Full schema reference for board editing
Visão geral
Cada quadro Kanban é apoiado por um documento Markdown de texto simples que você pode ler, escrever, copiar e controlar a versão. O documento tem duas seções: um bloco Estruturado legível por máquina que contém os dados do quadro como JSON e um bloco Personalizado de formato livre para suas anotações pessoais.
Sempre faça o teste primeiro
Antes de clicar em Aplicar, use o botão Teste para validar suas edições. O back-end reportará erros e um resumo das diferenças sem modificar seu quadro.
Estrutura do Documento
Um documento Kanban Markdown completo é composto de três partes:
- Um cabeçalho legível (título do quadro, nota de geração)
- O bloco estruturado — dados JSON entre marcadores de comentários HTML
- O Bloco personalizado — Markdown gratuito (notas, diagramas de sereia, links)
# 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 -->Não remova os marcadores de comentários
Os marcadores <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> são obrigatórios. Removê-los causa um erro de análise.
Colunas
As colunas definem os estágios do fluxo de trabalho do seu quadro. Eles são renderizados da esquerda para a direita por seu valor 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 | — | Identificador de coluna exclusivo (UUID ou qualquer slug estável) |
title | string | Yes | — | Título da coluna mostrado no quadro |
color | string | Yes | #64748b | Cor de destaque da coluna (hex). Mostrado como borda esquerda nos cartões |
order | integer | Yes | — | Ordem de exibição baseada em zero (crescente, da esquerda para a direita) |
Note
Os IDs das colunas devem ser exclusivos no quadro. Colunas de referência de tarefas por este id.
Tarefas
As tarefas são a unidade central do trabalho. Cada tarefa reside dentro de uma coluna (via columnId) e é classificada por position dentro dessa coluna.
Tarefa mínima
{
"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": []
}Tarefa completa com todos os campos
{
"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 | — | Identificador exclusivo de tarefa (UUID ou slug estável) |
columnId | string | Yes | — | ID da coluna à qual esta tarefa pertence |
position | integer | Yes | — | Ordem de classificação baseada em zero na coluna |
title | string | Yes | — | Título da tarefa (1–280 caracteres) |
description | string | No | "" | Descrição mais longa compatível com Markdown |
priority | enum "low""medium""high""critical" | No | medium | Nível de urgência da tarefa |
tags | string[] | No | [] | Strings de rótulos de formato livre para filtragem e agrupamento |
assigneeIds | string[] | No | [] | IDs de membros de pessoas atribuídas a esta tarefa |
mentionMemberIds | string[] | No | [] | IDs de membros mencionados (notificados) nesta tarefa |
estimatePoints | integer|null | No | null | Estimativa de pontos da história (Fibonacci: 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | Sequência de data ISO 8601: AAAA-MM-DD |
plannedStartAt | string|null | No | null | Data e hora ISO 8601: início planejado |
plannedEndAt | string|null | No | null | Data e hora ISO 8601: fim planejado |
timeboxMinutes | integer|null | No | null | Duração da sessão de foco para time-boxing |
isCompleted | boolean | No | false | Marca a tarefa como concluída (adiciona tachado na interface do usuário) |
archivedAt | string|null | No | null | Data e hora ISO 8601 quando a tarefa foi arquivada. As tarefas arquivadas ficam ocultas no quadro |
checklist | object[] | No | [] | Itens da lista de verificação de subtarefas (consulte a seção Lista de verificação) |
Itens da lista de verificação
Cada tarefa suporta uma lista simples de itens da lista de verificação – subtarefas leves que podem ser marcadas individualmente como concluídas sem criar tarefas separadas.
"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 | — | Etiqueta do item da lista de verificação (1–255 caracteres) |
isDone | boolean | Yes | — | Se este item está marcado |
Seção de notas personalizadas
Tudo entre <!-- KANBAN:CUSTOM:START --> e <!-- KANBAN:CUSTOM:END --> é o seu bloco de notas. Ele suporta diagramas Markdown e Mermaid completos. O conteúdo nunca é analisado pelo mecanismo da placa — ele é mostrado apenas na guia Visualização.
<!-- 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
Use a seção Personalizada para notas de sprint, links de equipe, gráficos de Gantt, diagramas de arquitetura – tudo o que você deseja que fique visível junto com os dados do quadro.
Valores prioritários
O campo priority aceita exatamente um dos quatro valores. Cada um mapeia para uma cor de emblema distinta na IU:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Baixa urgência. Mostrado em ardósia/cinza. |
medium | enum value | No | — | Padrão. Mostrado em âmbar/amarelo. Omitir o padrão de prioridade para isso. |
high | enum value | No | — | Importante. Mostrado em laranja. |
critical | enum value | No | — | Bloqueio. Mostrado em vermelho/rosa. |
Arquivando Tarefas
Para arquivar uma tarefa, defina seu campo archivedAt como uma string de data e hora ISO. As tarefas arquivadas são excluídas da visualização ativa do quadro, mas preservadas no histórico.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
Definir archivedAt como null desarquiva a tarefa. O resumo de diferenças mostrará tasksToArchive ao aplicar um instantâneo de redução que arquiva as tarefas atualmente ativas no quadro.
Teste e diagnóstico
O recurso Dry-run valida sua redução sem aplicar alterações. O backend retorna um array diffSummary (o que mudaria) e um array diagnostics listando quaisquer erros ou avisos.
Resposta de simulação bem-sucedida
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Teste com erros
{
"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 | — | Código de erro legível por máquina (por exemplo, desconhecido_column_id) |
message | string | Yes | — | Descrição legível do problema |
line | integer | Yes | — | Número aproximado da linha no documento de redução |
severity | enum "error""warning" | Yes | — | Ou 'erro' (aplicam-se bloqueios) ou 'aviso' (aplicam-se procedimentos) |
Bloco de erros Aplicar
Se o diagnóstico contiver algum item com gravidade: 'erro', a operação Aplicar se recusará a prosseguir. Os avisos são consultivos e não bloqueiam.
Fluxo de trabalho recomendado
Siga este fluxo ao editar o quadro via Markdown:
- Abra o painel Markdown em seu quadro
- Edite o JSON no Bloco estruturado — adicione/modifique colunas ou tarefas
- Clique em Teste para validar sem alterar nada
- Corrija quaisquer erros mostrados na lista de diagnósticos
- Clique em Aplicar para confirmar as alterações no quadro ativo
- Use Download para salvar um backup local
.md
Dica de controle de versão
Como o documento é um texto simples, você pode colá-lo em um repositório Git, comparar versões e restaurar estados anteriores do quadro reaplicando um instantâneo mais antigo.