Markdown & JSON Reference
Full schema reference for board editing
نمای کلی
هر برد Kanban توسط یک سند Markdown متن ساده پشتیبانی می شود که می توانید آن را بخوانید، بنویسید، کپی کنید و نسخه را کنترل کنید. این سند دارای دو بخش است: یک بلوک ساختار یافته قابل خواندن توسط ماشین که داده های برد را به صورت JSON نگهداری می کند و یک بلوک سفارشی آزاد برای یادداشت های شخصی شما.
همیشه ابتدا به صورت خشک کار کنید
قبل از کلیک بر روی Apply، از دکمه Dry-run برای تایید ویرایش های خود استفاده کنید. پشتیبان خطاها و خلاصه تفاوت را بدون تغییر تابلوی شما گزارش خواهد کرد.
ساختار سند
یک سند کامل 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 یا Slug پایدار) |
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: YYYY-MM-DD |
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، کار را بایگانی می کند. خلاصه تفاوت tasksToArchive را هنگام اعمال یک عکس فوری نشانه گذاری نشان می دهد که وظایفی را که در حال حاضر روی برد فعال هستند بایگانی می کند.
خشک اجرا و تشخیص
ویژگی Dry-run علامت گذاری شما را بدون اعمال تغییرات تأیید می کند. باطن یک آرایه 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 | — | کد خطای قابل خواندن توسط ماشین (به عنوان مثال شناسه_column_known) |
message | string | Yes | — | توصیف انسان قابل خواندن از موضوع |
line | integer | Yes | — | شماره خط تقریبی در سند علامت گذاری |
severity | enum "error""warning" | Yes | — | یا "خطا" (بلاک ها اعمال می شوند) یا "اخطار" (اعمال درآمد) |
خطاها بلوک اعمال کنید
اگر تشخیص حاوی مواردی با شدت باشد: «خطا»، عملیات Apply از ادامه دادن امتناع خواهد کرد. هشدارها توصیه ای هستند و مسدود نمی شوند.
گردش کار توصیه شده
هنگام ویرایش تابلو از طریق Markdown این جریان را دنبال کنید:
- پانل Markdown را روی برد خود باز کنید
- JSON را در بلوک ساختاریافته ویرایش کنید — ستون ها یا وظایف را اضافه/تغییر دهید
- روی Dry-run کلیک کنید تا بدون تغییر چیزی تایید شود
- هر گونه خطای نشان داده شده در لیست عیب یابی را برطرف کنید
- روی اعمال کلیک کنید تا تغییرات را در صفحه زنده انجام دهید
- برای ذخیره یک نسخه پشتیبان محلی
.mdاز Download استفاده کنید
نکته کنترل نسخه
از آنجایی که سند یک متن ساده است، میتوانید آن را در یک مخزن Git جایگذاری کنید، نسخههای مختلف را تغییر دهید و با اعمال مجدد یک عکس قدیمیتر، حالتهای قبلی برد را بازیابی کنید.