Markdown & JSON Reference
Full schema reference for board editing
Descripción general
Cada tablero Kanban está respaldado por un documento Markdown de texto sin formato que puede leer, escribir, copiar y controlar las versiones. El documento tiene dos secciones: un bloque Estructurado legible por máquina que contiene los datos del tablero como JSON y un bloque Personalizado de formato libre para sus notas personales.
Siempre haga primero el funcionamiento en seco
Antes de hacer clic en Aplicar, utilice el botón Ejecución en seco para validar sus ediciones. El backend informará errores y un resumen de diferencias sin modificar su tablero.
Estructura del documento
Un documento Kanban Markdown completo se compone de tres partes:
- Un encabezado legible por humanos (título del tablero, nota de generación)
- El bloque estructurado: datos JSON entre marcadores de comentarios HTML
- El bloque personalizado: Markdown gratuito (notas, diagramas de sirena, enlaces)
# 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 -->No eliminar los marcadores de comentarios.
Los marcadores <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> y <!-- KANBAN:CUSTOM:END --> son obligatorios. Eliminarlos provoca un error de análisis.
columnas
Las columnas definen las etapas del flujo de trabajo de su tablero. Se representan de izquierda a derecha según su 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 columna único (UUID o cualquier slug estable) |
title | string | Yes | — | Encabezado de columna mostrado en el tablero |
color | string | Yes | #64748b | Color de acento de columna (hexadecimal). Se muestra como borde izquierdo en las tarjetas. |
order | integer | Yes | — | Orden de visualización de base cero (ascendente, de izquierda a derecha) |
Note
Los ID de las columnas deben ser únicos dentro del tablero. Columnas de referencia de tareas de este id.
Tareas
Las tareas son la unidad central de trabajo. Cada tarea se encuentra dentro de una columna (a través de columnId) y está ordenada por position dentro de esa columna.
Tarea 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": []
}Tarea completa con todos los 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 de tarea único (UUID o slug estable) |
columnId | string | Yes | — | ID de la columna a la que pertenece esta tarea |
position | integer | Yes | — | Orden de clasificación de base cero dentro de la columna |
title | string | Yes | — | Título de la tarea (1–280 caracteres) |
description | string | No | "" | Descripción más larga compatible con Markdown |
priority | enum "low""medium""high""critical" | No | medium | Nivel de urgencia de la tarea |
tags | string[] | No | [] | Cadenas de etiquetas de forma libre para filtrar y agrupar |
assigneeIds | string[] | No | [] | ID de miembro de las personas asignadas a esta tarea |
mentionMemberIds | string[] | No | [] | ID de miembros mencionados (notificados) en esta tarea |
estimatePoints | integer|null | No | null | Estimación del punto de la historia (Fibonacci: 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | Cadena de fecha ISO 8601: AAAA-MM-DD |
plannedStartAt | string|null | No | null | Fecha y hora ISO 8601: inicio previsto |
plannedEndAt | string|null | No | null | Fecha y hora ISO 8601: finalización prevista |
timeboxMinutes | integer|null | No | null | Duración de la sesión de enfoque para el timeboxing |
isCompleted | boolean | No | false | Marca la tarea como realizada (agrega tachado en la interfaz de usuario) |
archivedAt | string|null | No | null | Fecha y hora ISO 8601 en la que se archivó la tarea. Las tareas archivadas están ocultas del tablero. |
checklist | object[] | No | [] | Elementos de la lista de verificación de subtareas (consulte la sección Lista de verificación) |
Elementos de la lista de verificación
Cada tarea admite una lista plana de elementos de la lista de verificación: subtareas livianas que se pueden marcar individualmente sin crear tareas 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 del elemento de la lista de verificación (de 1 a 255 caracteres) |
isDone | boolean | Yes | — | Si este elemento está marcado |
Sección de notas personalizadas
Todo lo que esté entre <!-- KANBAN:CUSTOM:START --> y <!-- KANBAN:CUSTOM:END --> es tu bloc de notas. Admite diagramas completos de Markdown y Mermaid. El contenido nunca es analizado por el motor de la placa; solo se muestra en la pestaña Vista previa.
<!-- 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
Utilice la sección Personalizada para notas de sprint, enlaces de equipo, diagramas de Gantt, diagramas de arquitectura: cualquier cosa que desee que esté visible junto con los datos de su tablero.
Valores de prioridad
El campo priority acepta exactamente uno de cuatro valores. Cada uno se asigna a un color de insignia distinto en la interfaz de usuario:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Urgencia baja. Se muestra en pizarra/gris. |
medium | enum value | No | — | Predeterminado. Se muestra en ámbar/amarillo. Omitir la prioridad por defecto es esto. |
high | enum value | No | — | Importante. Se muestra en naranja. |
critical | enum value | No | — | Bloqueo. Se muestra en rojo/rosa. |
Tareas de archivo
Para archivar una tarea, configure su campo archivedAt en una cadena de fecha y hora ISO. Las tareas archivadas se excluyen de la vista del tablero activo, pero se conservan en el historial.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
Establecer archivedAt en nulo desarchiva la tarea. El resumen de diferencias mostrará tareas para archivar al aplicar una instantánea de rebajas que archiva las tareas actualmente activas en el tablero.
Ejecución en seco y diagnóstico
La función de ejecución en seco valida su descuento sin aplicar cambios. El backend devuelve un diffSummary (lo que cambiaría) y una matriz diagnostics que enumera los errores o advertencias.
Respuesta exitosa al ensayo
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Ejecución en seco con errores
{
"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 error legible por máquina (por ejemplo, desconocido_columna_id) |
message | string | Yes | — | Descripción legible por humanos del problema |
line | integer | Yes | — | Número de línea aproximado en el documento de rebajas. |
severity | enum "error""warning" | Yes | — | Ya sea 'error' (se aplican bloqueos) o 'advertencia' (se aplican ingresos) |
Bloque de errores Aplicar
Si el diagnóstico contiene algún elemento con gravedad: "error", la operación Aplicar se negará a continuar. Las advertencias son de asesoramiento y no bloquean.
Flujo de trabajo recomendado
Siga este flujo al editar el tablero a través de Markdown:
- Abre el panel Markdown en tu tablero
- Edite el JSON en el bloque estructurado: agregue/modifique columnas o tareas
- Haga clic en Ejecución en seco para validar sin cambiar nada.
- Corrija los errores que se muestran en la lista de diagnósticos.
- Haga clic en Aplicar para confirmar los cambios en el tablero en vivo.
- Utilice Descargar para guardar una copia de seguridad local
.md
Consejo de control de versiones
Debido a que el documento es texto sin formato, puede pegarlo en un repositorio de Git, comparar versiones y restaurar estados anteriores del tablero volviendo a aplicar una instantánea anterior.