Markdown & JSON Reference
Full schema reference for board editing
Обзор
Каждая доска Канбан поддерживается обычным текстовым документом Markdown, который вы можете читать, писать, копировать и контролировать версии. Документ состоит из двух разделов: машиночитаемого блока Структурированный, содержащего данные доски в формате JSON, и блока Пользовательский произвольной формы для ваших личных заметок.
Всегда сначала проводите сухой прогон
Прежде чем нажать «Применить», используйте кнопку «Пробный прогон», чтобы подтвердить внесенные изменения. Серверная часть сообщит об ошибках и предоставит сводную информацию о различиях без внесения изменений в вашу плату.
Структура документа
Полный документ Kanban Markdown состоит из трех частей:
- Удобочитаемый заголовок (заголовок доски, примечание о поколении)
- Структурированный блок — данные JSON между маркерами комментариев HTML.
- Пользовательский блок — бесплатный Markdown (заметки, диаграммы Русалок, ссылки)
# 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 -->Не удаляйте маркеры комментариев
Маркеры <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> и <!-- KANBAN:CUSTOM:END --> являются обязательными. Их удаление приводит к ошибке синтаксического анализа.
Столбцы
Столбцы определяют этапы рабочего процесса вашей доски. Они отображаются слева направо по значению 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 | — | Уникальный идентификатор столбца (UUID или любой стабильный фрагмент) |
title | string | Yes | — | Заголовок столбца отображается на доске |
color | string | Yes | #64748b | Цвет акцента столбца (шестнадцатеричный). Отображается как левая граница на карточках |
order | integer | Yes | — | Порядок отображения с отсчетом от нуля (по возрастанию, слева направо) |
Note
Идентификаторы столбцов должны быть уникальными внутри доски. Задачи ссылаются на столбцы по этому id.
Задачи
Задачи — это основная единица работы. Каждая задача находится внутри столбца (через columnId) и сортируется по position внутри этого столбца.
Минимальная задача
{
"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": []
}Полное задание со всеми полями
{
"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 | — | Уникальный идентификатор задачи (UUID или стабильный фрагмент) |
columnId | string | Yes | — | Идентификатор столбца, к которому принадлежит эта задача |
position | integer | Yes | — | Порядок сортировки с отсчетом от нуля внутри столбца |
title | string | Yes | — | Название задачи (1–280 символов) |
description | string | No | "" | Подробное описание, совместимое с Markdown |
priority | enum "low""medium""high""critical" | No | medium | Уровень срочности задачи |
tags | string[] | No | [] | Строки меток произвольной формы для фильтрации и группировки. |
assigneeIds | string[] | No | [] | Идентификаторы участников людей, которым назначена эта задача |
mentionMemberIds | string[] | No | [] | Идентификаторы участников, упомянутые (уведомленные) в этой задаче |
estimatePoints | integer|null | No | null | Оценка сюжетных точек (Фибоначчи: 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | Строка даты ISO 8601: ГГГГ-ММ-ДД. |
plannedStartAt | string|null | No | null | Дата и время ISO 8601: запланированное начало |
plannedEndAt | string|null | No | null | Дата и время ISO 8601: запланированное завершение |
timeboxMinutes | integer|null | No | null | Продолжительность фокус-сессии для тайм-бокса |
isCompleted | boolean | No | false | Отмечает задачу как выполненную (добавляет зачеркивание в пользовательском интерфейсе) |
archivedAt | string|null | No | null | Дата и время ISO 8601, когда задача была заархивирована. Архивированные задачи скрыты с доски |
checklist | object[] | No | [] | Пункты контрольного списка подзадач (см. раздел Контрольный список) |
Пункты контрольного списка
Каждая задача поддерживает плоский список элементов контрольного списка — легкие подзадачи, которые можно индивидуально пометить как выполненные, не создавая отдельные задачи.
"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 | — | Ярлык элемента контрольного списка (1–255 символов) |
isDone | boolean | Yes | — | Отмечен ли этот элемент |
Раздел пользовательских заметок
Все, что находится между <!-- KANBAN:CUSTOM:START --> и <!-- KANBAN:CUSTOM:END --> — это ваш блокнот. Он поддерживает полные диаграммы Markdown и Mermaid. Содержимое никогда не анализируется движком доски — оно отображается только на вкладке «Предварительный просмотр».
<!-- 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
Используйте раздел «Пользовательский» для заметок спринта, ссылок на команды, диаграмм Ганта, архитектурных диаграмм — всего, что вы хотите видеть рядом с данными вашей доски.
Приоритетные значения
Поле priority принимает ровно одно из четырех значений. Каждому соответствует отдельный цвет значка в пользовательском интерфейсе:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Низкая срочность. Показан в синевато-сером цвете. |
medium | enum value | No | — | По умолчанию. Показан янтарным/желтым цветом. Опуская при этом приоритеты по умолчанию. |
high | enum value | No | — | Важно. Показано оранжевым цветом. |
critical | enum value | No | — | Блокировка. Показан в красном/розовом цвете. |
Архивирование задач
Чтобы заархивировать задачу, установите в ее поле archivedAt строку даты и времени ISO. Архивированные задачи исключаются из активной доски, но сохраняются в истории.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
Установка для archivedAt значения null разархивирует задачу. В сводке различий будет отображаться TaskToArchive при применении снимка уценки, который архивирует задачи, активные в данный момент на доске.
Сухой ход и диагностика
Функция пробного прогона проверяет вашу уценку без применения изменений. Серверная часть возвращает массив diffSummary (что изменится) и массив diagnostics со списком любых ошибок или предупреждений.
Успешный ответ на пробный ход
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Пробный прогон с ошибками
{
"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 | — | Машиночитаемый код ошибки (например,known_column_id) |
message | string | Yes | — | Понятное описание проблемы |
line | integer | Yes | — | Приблизительный номер строки в документе уценки |
severity | enum "error""warning" | Yes | — | Либо «ошибка» (блокировка применяется), либо «предупреждение» (применяется выручка) |
Блок ошибок Применить
Если диагностика содержит какой-либо элемент с уровнем серьезности: «ошибка», операция «Применить» не будет продолжена. Предупреждения носят рекомендательный характер и не блокируют.
Рекомендуемый рабочий процесс
Следуйте этому алгоритму при редактировании доски через Markdown:
- Откройте панель Markdown на своей доске.
- Отредактируйте JSON в Структурированном блоке — добавьте/измените столбцы или задачи.
- Нажмите Пробный запуск, чтобы подтвердить ничего не меняя.
- Исправьте все ошибки, показанные в списке диагностики.
- Нажмите Применить, чтобы внести изменения в живую доску.
- Используйте Загрузить, чтобы сохранить локальную резервную копию
.md
Совет по контролю версий
Поскольку документ представляет собой обычный текст, вы можете вставить его в репозиторий Git, сравнить версии и восстановить предыдущие состояния платы, повторно применив старый снимок.