Kanban StudioMarkdown & JSON Reference
📝

Markdown & JSON Reference

Full schema reference for board editing

Aperçu

Chaque tableau Kanban est soutenu par un document Markdown en texte brut que vous pouvez lire, écrire, copier et contrôler les versions. Le document comporte deux sections : un bloc Structured lisible par machine contenant les données du tableau au format JSON, et un bloc Personnalisé de forme libre pour vos notes personnelles.

Schéma v1JSON + démarqueSécurité contre la marche à sec
💡

Toujours faire un essai à sec en premier

Avant de cliquer sur Appliquer, utilisez le bouton Exécution à sec pour valider vos modifications. Le backend signalera les erreurs et un résumé des différences sans modifier votre tableau.

Structure des documents

Un document Kanban Markdown complet est composé de trois parties :

  • Un en-tête lisible par l'homme (titre du forum, note de génération)
  • Le Bloc structuré — Données JSON entre les marqueurs de commentaires HTML
  • Le Bloc personnalisé — Markdown gratuit (notes, diagrammes Mermaid, liens)
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 -->
Document complet du conseil d'administration avec toutes les sections annotées
⚠️

Ne supprimez pas les marqueurs de commentaires

Les marqueurs <!-- KANBAN:STRUCTURED:START -->, <!-- KANBAN:STRUCTURED:END -->, <!-- KANBAN:CUSTOM:START --> et <!-- KANBAN:CUSTOM:END --> sont requis. Les supprimer provoque une erreur d’analyse.

Colonnes

Les colonnes définissent les étapes du flux de travail de votre tableau. Ils sont rendus de gauche à droite par leur valeur 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 }
]
Exemple : quatre colonnes avec des couleurs distinctes
FieldTypeRequiredDescription
idstringYesIdentificateur de colonne unique (UUID ou tout autre slug stable)
titlestringYesEn-tête de colonne affiché au tableau
colorstringYesCouleur d’accentuation des colonnes (hexadécimal). Affiché comme bordure gauche sur les cartes
orderintegerYesOrdre d'affichage basé sur zéro (croissant, de gauche à droite)
ℹ️

Note

Les ID de colonne doivent être uniques au sein du tableau. Les tâches référencent les colonnes par ce id.

Tâches

Les tâches constituent l'unité de travail principale. Chaque tâche se trouve dans une colonne (via columnId) et est triée par position dans cette colonne.

Tâche minimale

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": []
}
Seuls les champs obligatoires sont remplis — tous les champs facultatifs sont nuls/vides

Tâche complète avec tous les champs

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 }
  ]
}
Exemple de production avec priorité, tags, responsables, liste de contrôle, suivi du temps
FieldTypeRequiredDescription
idstringYesIdentifiant unique de la tâche (UUID ou stable slug)
columnIdstringYesID de la colonne à laquelle appartient cette tâche
positionintegerYesOrdre de tri basé sur zéro dans la colonne
titlestringYesTitre de la tâche (1 à 280 caractères)
descriptionstringNoDescription plus longue compatible avec Markdown
priorityenum
"low""medium""high""critical"
NoNiveau d'urgence de la tâche
tagsstring[]NoChaînes d'étiquettes de forme libre pour le filtrage et le regroupement
assigneeIdsstring[]NoID de membre des personnes affectées à cette tâche
mentionMemberIdsstring[]NoID de membre mentionnés (notifiés) dans cette tâche
estimatePointsinteger|nullNoEstimation du story-point (Fibonacci : 1, 2, 3, 5, 8, 13…)
dueDatestring|nullNoChaîne de date ISO 8601 : AAAA-MM-JJ
plannedStartAtstring|nullNoDateheure ISO 8601 : début prévu
plannedEndAtstring|nullNoDateheure ISO 8601 : fin prévue
timeboxMinutesinteger|nullNoDurée de la séance de concentration pour le time-boxing
isCompletedbooleanNoMarque la tâche comme terminée (ajoute un barré dans l'interface utilisateur)
archivedAtstring|nullNoDate/heure ISO 8601 à laquelle la tâche a été archivée. Les tâches archivées sont masquées du tableau
checklistobject[]NoÉléments de la liste de contrôle des sous-tâches (voir la section Liste de contrôle)

Éléments de la liste de contrôle

Chaque tâche prend en charge une liste plate d'éléments de liste de contrôle : des sous-tâches légères qui peuvent être marquées individuellement comme terminées sans créer de tâches distinctes.

JSON
"checklist": [
  { "title": "Design mockup",   "isDone": true  },
  { "title": "Code review",     "isDone": false },
  { "title": "Deploy to prod",  "isDone": false }
]
Trois éléments de la liste de contrôle : le premier terminé, les deux restants
FieldTypeRequiredDescription
titlestringYesÉtiquette de l'élément de la liste de contrôle (1 à 255 caractères)
isDonebooleanYesSi cet élément est coché

Section Notes personnalisées

Tout ce qui se trouve entre <!-- KANBAN:CUSTOM:START --> et <!-- KANBAN:CUSTOM:END --> est votre bloc-notes. Il prend en charge les diagrammes Markdown et Mermaid complets. Le contenu n'est jamais analysé par le moteur de la carte — il est uniquement affiché dans l'onglet Aperçu.

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 -->
Notes avec un diagramme de Gantt Sirène
💡

Tip

Utilisez la section Personnalisée pour les notes de sprint, les liens d'équipe, les diagrammes de Gantt, les diagrammes d'architecture — tout ce que vous souhaitez voir à côté des données de votre tableau.

Valeurs prioritaires

Le champ priority accepte exactement une des quatre valeurs. Chacun correspond à une couleur de badge distincte dans l'interface utilisateur :

FieldTypeRequiredDescription
lowenum valueNoFaible urgence. Présenté en ardoise/gris.
mediumenum valueNoPar défaut. Montré en ambre/jaune. L'omission de la priorité par défaut est celle-ci.
highenum valueNoImportant. Montré en orange.
criticalenum valueNoBlocage. Montré en rouge/rose.

Tâches d'archivage

Pour archiver une tâche, définissez son champ archivedAt sur une chaîne datetime ISO. Les tâches archivées sont exclues de la vue active du tableau mais préservées dans l'historique.

JSON
{
  "id": "task-old",
  "columnId": "col-1",
  "position": 99,
  "title": "Old completed task",
  "archivedAt": "2025-01-10T14:30:00.000Z",
  ...
}
Tâche archivée : masquée du tableau, conservée dans l'instantané
ℹ️

Note

La définition de archivedAt sur null désarchive la tâche. Le résumé des différences affichera tâchesToArchive lors de l'application d'un instantané de démarque qui archive les tâches actuellement actives sur le tableau.

Essais à sec et diagnostics

La fonction Dry-run valide votre démarque sans appliquer de modifications. Le backend renvoie un tableau diffSummary (ce qui changerait) et un tableau diagnostics répertoriant les erreurs ou les avertissements.

Réponse réussie à un essai à sec

JSON
{
  "ok": true,
  "dryRun": true,
  "diagnostics": [],
  "diffSummary": {
    "columnsCreated": 1,
    "columnsTouched": 2,
    "tasksCreated": 3,
    "tasksTouched": 5,
    "tasksToArchive": 0
  }
}
ok : vrai signifie que la démarque est valide et peut être appliquée en toute sécurité

Essai à sec avec erreurs

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 – corrigez les erreurs avant de postuler
FieldTypeRequiredDescription
codestringYesCode d'erreur lisible par machine (par exemple, unknown_column_id)
messagestringYesDescription lisible du problème
lineintegerYesNuméro de ligne approximatif dans le document de démarque
severityenum
"error""warning"
YesSoit « erreur » (les blocages s'appliquent) ou « avertissement » (appliquer le produit)
🚫

Blocage des erreurs Appliquer

Si les diagnostics contiennent un élément de gravité : « erreur », l'opération Appliquer refusera de se poursuivre. Les avertissements sont consultatifs et ne bloquent pas.

Flux de travail recommandé

Suivez ce flux lors de la modification du tableau via Markdown :

  • Ouvrez le panneau Markdown sur votre tableau
  • Modifiez le JSON dans le Bloc structuré — ajoutez/modifiez des colonnes ou des tâches
  • Cliquez sur Dry-run pour valider sans rien changer
  • Corrigez toutes les erreurs affichées dans la liste de diagnostics
  • Cliquez sur Appliquer pour valider les modifications sur le tableau en direct.
  • Utilisez Télécharger pour enregistrer une sauvegarde locale de .md
💡

Astuce pour le contrôle des versions

Étant donné que le document est du texte brut, vous pouvez le coller dans un référentiel Git, des versions différentes et restaurer les états précédents de la carte en réappliquant un ancien instantané.

Schema v1 · Updated September 2026