Markdown & JSON Reference
Full schema reference for board editing
Ikhtisar
Setiap papan Kanban didukung oleh dokumen Markdown teks biasa yang dapat Anda baca, tulis, salin, dan kontrol versi. Dokumen ini memiliki dua bagian: blok Terstruktur yang dapat dibaca mesin yang menyimpan data papan sebagai JSON, dan blok Kustom bentuk bebas untuk catatan pribadi Anda.
Selalu keringkan terlebih dahulu
Sebelum mengklik Terapkan, gunakan tombol Uji coba untuk memvalidasi hasil edit Anda. Backend akan melaporkan kesalahan dan ringkasan perbedaan tanpa mengubah papan Anda.
Struktur Dokumen
Dokumen lengkap Kanban Markdown terdiri dari tiga bagian:
- Header yang dapat dibaca manusia (judul papan, catatan pembuatan)
- Blok terstruktur — data JSON antara penanda komentar HTML
- Blok khusus — Penurunan Harga gratis (catatan, diagram Mermaid, tautan)
# 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 -->Jangan hapus penanda komentar
Marker <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START -->, dan <!-- KANBAN:CUSTOM:END --> wajib diisi. Menghapusnya menyebabkan kesalahan penguraian.
Kolom
Kolom menentukan tahapan alur kerja papan Anda. Mereka dirender dari kiri ke kanan berdasarkan nilai order mereka.
"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 | — | Pengidentifikasi kolom unik (UUID atau slug stabil apa pun) |
title | string | Yes | — | Judul kolom ditampilkan di papan tulis |
color | string | Yes | #64748b | Warna aksen kolom (hex). Ditampilkan sebagai batas kiri pada kartu |
order | integer | Yes | — | Urutan tampilan berbasis nol (menaik, kiri-ke-kanan) |
Note
ID kolom harus unik di dalam papan. Kolom referensi tugas oleh id ini.
Tugas
Tugas adalah unit inti pekerjaan. Setiap tugas berada di dalam kolom (melalui columnId) dan diurutkan berdasarkan position di dalam kolom tersebut.
Tugas minimal
{
"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": []
}Tugas penuh dengan segala bidang
{
"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 | — | Pengidentifikasi tugas unik (UUID atau slug stabil) |
columnId | string | Yes | — | ID kolom tempat tugas ini berada |
position | integer | Yes | — | Urutan berdasarkan nol dalam kolom |
title | string | Yes | — | Judul tugas (1–280 karakter) |
description | string | No | "" | Deskripsi lebih panjang yang kompatibel dengan penurunan harga |
priority | enum "low""medium""high""critical" | No | medium | Tingkat urgensi tugas |
tags | string[] | No | [] | String label bentuk bebas untuk memfilter dan mengelompokkan |
assigneeIds | string[] | No | [] | ID anggota dari orang-orang yang ditugaskan untuk tugas ini |
mentionMemberIds | string[] | No | [] | ID anggota disebutkan (diberitahukan) dalam tugas ini |
estimatePoints | integer|null | No | null | Perkiraan titik cerita (Fibonacci: 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | String tanggal ISO 8601: YYYY-MM-DD |
plannedStartAt | string|null | No | null | Tanggal waktu ISO 8601: rencana awal |
plannedEndAt | string|null | No | null | Tanggal waktu ISO 8601: akhir yang direncanakan |
timeboxMinutes | integer|null | No | null | Durasi sesi fokus untuk pengatur waktu |
isCompleted | boolean | No | false | Menandai tugas sebagai selesai (menambahkan coretan di UI) |
archivedAt | string|null | No | null | Tanggal waktu ISO 8601 saat tugas diarsipkan. Tugas yang diarsipkan disembunyikan dari papan |
checklist | object[] | No | [] | Item daftar periksa sub-tugas (lihat bagian Daftar Periksa) |
Item Daftar Periksa
Setiap tugas mendukung daftar item daftar periksa yang datar — subtugas ringan yang dapat ditandai secara individual sebagai selesai tanpa membuat tugas terpisah.
"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 | — | Label item daftar periksa (1–255 karakter) |
isDone | boolean | Yes | — | Apakah item ini dicentang |
Bagian Catatan Khusus
Segala sesuatu di antara <!-- KANBAN:CUSTOM:START --> dan <!-- KANBAN:CUSTOM:END --> adalah papan gores Anda. Ini mendukung diagram Markdown dan Mermaid penuh. Konten tersebut tidak pernah diurai oleh mesin papan — konten hanya ditampilkan di tab Pratinjau.
<!-- 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
Gunakan bagian Kustom untuk catatan sprint, tautan tim, bagan Gantt, diagram arsitektur — apa pun yang Anda ingin terlihat di samping data papan Anda.
Nilai Prioritas
Bidang priority menerima tepat satu dari empat nilai. Masing-masing dipetakan ke warna lencana yang berbeda di UI:
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Urgensi rendah. Ditampilkan dalam warna batu tulis/abu-abu. |
medium | enum value | No | — | Bawaan. Ditampilkan dalam warna kuning/kuning. Menghilangkan default prioritas untuk ini. |
high | enum value | No | — | Penting. Ditampilkan dalam warna oranye. |
critical | enum value | No | — | Memblokir. Ditampilkan dalam warna merah/mawar. |
Tugas Pengarsipan
Untuk mengarsipkan tugas, setel bidang archivedAt ke string tanggalwaktu ISO. Tugas yang diarsipkan dikecualikan dari tampilan papan aktif tetapi disimpan dalam riwayat.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}Note
Menyetel archivedAt ke null membatalkan pengarsipan tugas. Ringkasan perbedaan akan menampilkan taskToArchive saat menerapkan snapshot penurunan harga yang mengarsipkan tugas yang saat ini aktif di papan.
Uji coba & Diagnostik
Fitur Dry-run memvalidasi penurunan harga Anda tanpa menerapkan perubahan. Backend mengembalikan array diffSummary (apa yang akan berubah) dan diagnostics yang mencantumkan kesalahan atau peringatan apa pun.
Respons uji coba yang berhasil
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Uji coba dengan kesalahan
{
"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 | — | Kode kesalahan yang dapat dibaca mesin (misalnya unknown_column_id) |
message | string | Yes | — | Deskripsi masalah yang dapat dibaca manusia |
line | integer | Yes | — | Perkiraan nomor baris dalam dokumen penurunan harga |
severity | enum "error""warning" | Yes | — | Entah 'kesalahan' (pemblokiran berlaku) atau 'peringatan' (penerapan dilanjutkan) |
Blok kesalahan Terapkan
Jika diagnostik berisi item apa pun dengan tingkat keparahan: 'kesalahan', operasi Terapkan akan menolak untuk melanjutkan. Peringatan bersifat nasihat dan tidak menghalangi.
Alur Kerja yang Direkomendasikan
Ikuti alur ini saat mengedit papan melalui Markdown:
- Buka panel Markdown di papan Anda
- Edit JSON di Blok terstruktur — menambah/memodifikasi kolom atau tugas
- Klik Dry-run untuk memvalidasi tanpa mengubah apa pun
- Perbaiki kesalahan apa pun yang ditampilkan dalam daftar diagnostik
- Klik Terapkan untuk melakukan perubahan pada papan langsung
- Gunakan Unduh untuk menyimpan cadangan
.mdlokal
Tip kontrol versi
Karena dokumennya berupa teks biasa, Anda dapat menempelkannya ke repositori Git, mengubah versi, dan memulihkan status papan sebelumnya dengan menerapkan kembali snapshot lama.