Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

نمای کلی

هر برد Kanban توسط یک سند Markdown متن ساده پشتیبانی می شود که می توانید آن را بخوانید، بنویسید، کپی کنید و نسخه را کنترل کنید. این سند دارای دو بخش است: یک بلوک ساختار یافته قابل خواندن توسط ماشین که داده های برد را به صورت JSON نگهداری می کند و یک بلوک سفارشی آزاد برای یادداشت های شخصی شما.

طرحواره v1JSON + Markdownایمن برای اجرای خشک
💡

همیشه ابتدا به صورت خشک کار کنید

قبل از کلیک بر روی Apply، از دکمه Dry-run برای تایید ویرایش های خود استفاده کنید. پشتیبان خطاها و خلاصه تفاوت را بدون تغییر تابلوی شما گزارش خواهد کرد.

ساختار سند

یک سند کامل Kanban Markdown از سه بخش تشکیل شده است:

  • هدر قابل خواندن برای انسان (عنوان تابلو، یادداشت نسل)
  • بلاک ساختاریافته - داده های JSON بین نشانگرهای نظر HTML
  • بلوک سفارشی — Markdown رایگان (یادداشت ها، نمودارهای پری دریایی، پیوندها)
board.md
# 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 آنها از چپ به راست رندر می شوند.

JSON
"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 }
]
مثال: چهار ستون با رنگ های متمایز
FieldTypeRequiredDescription
idstringYesشناسه ستون منحصر به فرد (UUID یا هر حلزون ثابت)
titlestringYesعنوان ستون روی تابلو نشان داده شده است
colorstringYesرنگ تاکیدی ستون (هگز). به عنوان حاشیه سمت چپ روی کارت ها نشان داده می شود
orderintegerYesترتیب نمایش بر اساس صفر (صعودی، چپ به راست)
ℹ️

Note

شناسه های ستون باید در تابلو منحصر به فرد باشد. ستون های وظایف با این id ارجاع می دهند.

وظایف

وظایف واحد اصلی کار هستند. هر کار در یک ستون (از طریق columnId) زندگی می کند و بر اساس position در آن ستون مرتب می شود.

کار حداقلی

JSON
{
  "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": []
}
فقط فیلدهای الزامی پر شده است - همه فیلدهای اختیاری تهی / خالی هستند

کار کامل با تمام فیلدها

JSON
{
  "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 }
  ]
}
نمونه تولید با اولویت، برچسب ها، واگذار شده ها، چک لیست، ردیابی زمان
FieldTypeRequiredDescription
idstringYesشناسه تکلیف (UUID یا Slug پایدار)
columnIdstringYesشناسه ستونی که این کار به آن تعلق دارد
positionintegerYesترتیب مرتب سازی بر اساس صفر در ستون
titlestringYesعنوان کار (1 تا 280 نویسه)
descriptionstringNoتوضیحات طولانی تر سازگار با Markdown
priorityenum
"low""medium""high""critical"
Noسطح فوریت کار
tagsstring[]Noرشته های برچسب آزاد برای فیلتر کردن و گروه بندی
assigneeIdsstring[]Noشناسه اعضای افرادی که به این کار اختصاص داده شده اند
mentionMemberIdsstring[]Noشناسه های عضو ذکر شده (اعلام شده) در این کار
estimatePointsinteger|nullNoتخمین نقطه داستان (فیبوناچی: 1، 2، 3، 5، 8، 13…)
dueDatestring|nullNoرشته تاریخ ISO 8601: YYYY-MM-DD
plannedStartAtstring|nullNoتاریخ تاریخ ISO 8601: شروع برنامه ریزی شده
plannedEndAtstring|nullNoتاریخ تاریخ ISO 8601: پایان برنامه ریزی شده
timeboxMinutesinteger|nullNoطول جلسه تمرکز برای تایم بوکس
isCompletedbooleanNoکار را به عنوان انجام شده علامت گذاری می کند (خط خطی را در رابط کاربری اضافه می کند)
archivedAtstring|nullNoISO 8601 تاریخ زمانی که کار بایگانی شد. وظایف بایگانی شده از هیئت مدیره پنهان می شوند
checklistobject[]Noموارد چک لیست زیر وظایف (به بخش چک لیست مراجعه کنید)

موارد چک لیست

هر کار از یک لیست مسطح از موارد چک لیست پشتیبانی می کند - وظایف فرعی سبکی که می توانند به صورت جداگانه بدون ایجاد وظایف جداگانه علامت گذاری شوند.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
سه مورد چک لیست: اول یکی انجام شد، دو مورد باقی مانده است
FieldTypeRequiredDescription
titlestringYesبرچسب آیتم چک لیست (1 تا 255 نویسه)
isDonebooleanYesآیا این مورد علامت زده شده است یا خیر

بخش یادداشت های سفارشی

همه چیز بین <!-- KANBAN:CUSTOM:START --> و <!-- KANBAN:CUSTOM:END --> صفحه خراش شما است. از نمودارهای Markdown و Mermaid کامل پشتیبانی می کند. محتوا هرگز توسط موتور برد تجزیه نمی شود - فقط در برگه پیش نمایش نشان داده می شود.

Markdown
<!-- 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 دقیقاً یکی از چهار مقدار را می‌پذیرد. هر نقشه به رنگ نشان مجزا در رابط کاربری نشان داده می شود:

FieldTypeRequiredDescription
lowenum valueNoفوریت کم به رنگ تخته سنگ/خاکستری نشان داده شده است.
mediumenum valueNoپیش فرض به رنگ کهربایی/زرد نشان داده شده است. حذف پیش‌فرض اولویت‌ها برای این.
highenum valueNoمهم است. به رنگ نارنجی نشان داده شده است.
criticalenum valueNoمسدود کردن. به رنگ قرمز/رز نشان داده شده است.

وظایف بایگانی

برای بایگانی یک کار، فیلد archivedAt آن را روی یک رشته تاریخ تاریخ ISO تنظیم کنید. کارهای بایگانی شده از نمای تابلوی فعال حذف شده اند اما در تاریخ حفظ می شوند.

JSON
{
  "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 را برمی‌گرداند که هر گونه خطا یا هشدار را فهرست می‌کند.

پاسخ خشک موفقیت آمیز

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: true به این معنی است که علامت گذاری معتبر و امن است

اجرای خشک با خطا

JSON
{
  "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
  }
}
ok: false - قبل از اعمال، خطاها را برطرف کنید
FieldTypeRequiredDescription
codestringYesکد خطای قابل خواندن توسط ماشین (به عنوان مثال شناسه_column_known)
messagestringYesتوصیف انسان قابل خواندن از موضوع
lineintegerYesشماره خط تقریبی در سند علامت گذاری
severityenum
"error""warning"
Yesیا "خطا" (بلاک ها اعمال می شوند) یا "اخطار" (اعمال درآمد)
🚫

خطاها بلوک اعمال کنید

اگر تشخیص حاوی مواردی با شدت باشد: «خطا»، عملیات Apply از ادامه دادن امتناع خواهد کرد. هشدارها توصیه ای هستند و مسدود نمی شوند.

گردش کار توصیه شده

هنگام ویرایش تابلو از طریق Markdown این جریان را دنبال کنید:

  • پانل Markdown را روی برد خود باز کنید
  • JSON را در بلوک ساختاریافته ویرایش کنید — ستون ها یا وظایف را اضافه/تغییر دهید
  • روی Dry-run کلیک کنید تا بدون تغییر چیزی تایید شود
  • هر گونه خطای نشان داده شده در لیست عیب یابی را برطرف کنید
  • روی اعمال کلیک کنید تا تغییرات را در صفحه زنده انجام دهید
  • برای ذخیره یک نسخه پشتیبان محلی .md از Download استفاده کنید
💡

نکته کنترل نسخه

از آنجایی که سند یک متن ساده است، می‌توانید آن را در یک مخزن Git جای‌گذاری کنید، نسخه‌های مختلف را تغییر دهید و با اعمال مجدد یک عکس قدیمی‌تر، حالت‌های قبلی برد را بازیابی کنید.

Schema v1 · Updated September 2026