Kanban Studio›Referensi Markdown & JSON
📝

Referensi Markdown & JSON

Referensi skema lengkap untuk pengeditan board

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.

Skema v1JSON + Penurunan HargaBrankas lari kering
💡

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)
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 -->
Dokumen papan lengkap dengan semua bagian diberi anotasi
⚠️

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.

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 }
]
Contoh: empat kolom dengan warna berbeda
BidangKetikDiperlukanDeskripsi
idstringYaPengidentifikasi kolom unik (UUID atau slug stabil apa pun)
titlestringYaJudul kolom ditampilkan di papan tulis
colorstringYaWarna aksen kolom (hex). Ditampilkan sebagai batas kiri pada kartu
orderintegerYaUrutan 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

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": []
}
Hanya bidang wajib yang diisi — semua bidang opsional adalah null/kosong

Tugas penuh dengan segala bidang

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 }
  ]
}
Contoh produksi dengan prioritas, tag, penerima tugas, daftar periksa, pelacakan waktu
BidangKetikDiperlukanDeskripsi
idstringYaPengidentifikasi tugas unik (UUID atau slug stabil)
columnIdstringYaID kolom tempat tugas ini berada
positionintegerYaUrutan berdasarkan nol dalam kolom
titlestringYaJudul tugas (1–280 karakter)
descriptionstringTidakDeskripsi lebih panjang yang kompatibel dengan penurunan harga
priorityenum
"low""medium""high""critical"
TidakTingkat urgensi tugas
tagsstring[]TidakString label bentuk bebas untuk memfilter dan mengelompokkan
assigneeIdsstring[]TidakID anggota dari orang-orang yang ditugaskan untuk tugas ini
mentionMemberIdsstring[]TidakID anggota disebutkan (diberitahukan) dalam tugas ini
estimatePointsinteger|nullTidakPerkiraan titik cerita (Fibonacci: 1, 2, 3, 5, 8, 13…)
dueDatestring|nullTidakString tanggal ISO 8601: YYYY-MM-DD
plannedStartAtstring|nullTidakTanggal waktu ISO 8601: rencana awal
plannedEndAtstring|nullTidakTanggal waktu ISO 8601: akhir yang direncanakan
timeboxMinutesinteger|nullTidakDurasi sesi fokus untuk pengatur waktu
isCompletedbooleanTidakMenandai tugas sebagai selesai (menambahkan coretan di UI)
archivedAtstring|nullTidakTanggal waktu ISO 8601 saat tugas diarsipkan. Tugas yang diarsipkan disembunyikan dari papan
checklistobject[]TidakItem 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.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Tiga item daftar periksa: yang pertama selesai, dua lagi
BidangKetikDiperlukanDeskripsi
titlestringYaLabel item daftar periksa (1–255 karakter)
isDonebooleanYaApakah 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.

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 -->
Catatan dengan bagan Mermaid Gantt
💡

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:

BidangKetikDiperlukanDeskripsi
lowenum valueTidakUrgensi rendah. Ditampilkan dalam warna batu tulis/abu-abu.
mediumenum valueTidakBawaan. Ditampilkan dalam warna kuning/kuning. Menghilangkan default prioritas untuk ini.
highenum valueTidakPenting. Ditampilkan dalam warna oranye.
criticalenum valueTidakMemblokir. 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.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
Tugas yang diarsipkan — disembunyikan dari papan, disimpan dalam snapshot
ℹ️

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

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok: true artinya markdown tersebut valid dan aman untuk diterapkan

Uji coba dengan kesalahan

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
  }
}
oke: salah — perbaiki kesalahan sebelum mengajukan permohonan
BidangKetikDiperlukanDeskripsi
codestringYaKode kesalahan yang dapat dibaca mesin (misalnya unknown_column_id)
messagestringYaDeskripsi masalah yang dapat dibaca manusia
lineintegerYaPerkiraan nomor baris dalam dokumen penurunan harga
severityenum
"error""warning"
YaEntah '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 .md lokal
💡

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.

Skema v1 · Diperbarui November 2026