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.
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)
# 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 -->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.
"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 | — | Identificateur de colonne unique (UUID ou tout autre slug stable) |
title | string | Yes | — | En-tête de colonne affiché au tableau |
color | string | Yes | #64748b | Couleur d’accentuation des colonnes (hexadécimal). Affiché comme bordure gauche sur les cartes |
order | integer | Yes | — | Ordre 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
{
"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": []
}Tâche complète avec tous les champs
{
"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 | — | Identifiant unique de la tâche (UUID ou stable slug) |
columnId | string | Yes | — | ID de la colonne à laquelle appartient cette tâche |
position | integer | Yes | — | Ordre de tri basé sur zéro dans la colonne |
title | string | Yes | — | Titre de la tâche (1 à 280 caractères) |
description | string | No | "" | Description plus longue compatible avec Markdown |
priority | enum "low""medium""high""critical" | No | medium | Niveau d'urgence de la tâche |
tags | string[] | No | [] | Chaînes d'étiquettes de forme libre pour le filtrage et le regroupement |
assigneeIds | string[] | No | [] | ID de membre des personnes affectées à cette tâche |
mentionMemberIds | string[] | No | [] | ID de membre mentionnés (notifiés) dans cette tâche |
estimatePoints | integer|null | No | null | Estimation du story-point (Fibonacci : 1, 2, 3, 5, 8, 13…) |
dueDate | string|null | No | null | Chaîne de date ISO 8601 : AAAA-MM-JJ |
plannedStartAt | string|null | No | null | Dateheure ISO 8601 : début prévu |
plannedEndAt | string|null | No | null | Dateheure ISO 8601 : fin prévue |
timeboxMinutes | integer|null | No | null | Durée de la séance de concentration pour le time-boxing |
isCompleted | boolean | No | false | Marque la tâche comme terminée (ajoute un barré dans l'interface utilisateur) |
archivedAt | string|null | No | null | Date/heure ISO 8601 à laquelle la tâche a été archivée. Les tâches archivées sont masquées du tableau |
checklist | object[] | 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.
"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 | — | Étiquette de l'élément de la liste de contrôle (1 à 255 caractères) |
isDone | boolean | Yes | — | Si 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.
<!-- 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
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 :
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
low | enum value | No | — | Faible urgence. Présenté en ardoise/gris. |
medium | enum value | No | — | Par défaut. Montré en ambre/jaune. L'omission de la priorité par défaut est celle-ci. |
high | enum value | No | — | Important. Montré en orange. |
critical | enum value | No | — | Blocage. 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.
{
"id": "task-old",
"columnId": "col-1",
"position": 99,
"title": "Old completed task",
"archivedAt": "2025-01-10T14:30:00.000Z",
...
}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
{
"ok": true,
"dryRun": true,
"diagnostics": [],
"diffSummary": {
"columnsCreated": 1,
"columnsTouched": 2,
"tasksCreated": 3,
"tasksTouched": 5,
"tasksToArchive": 0
}
}Essai à sec avec erreurs
{
"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 | — | Code d'erreur lisible par machine (par exemple, unknown_column_id) |
message | string | Yes | — | Description lisible du problème |
line | integer | Yes | — | Numéro de ligne approximatif dans le document de démarque |
severity | enum "error""warning" | Yes | — | Soit « 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é.