Schéma de Tableau Kanban Fancy

Une spécification autonome pour le format de tableau kanban basé sur Markdown. Toute application lisant et écrivant des fichiers suivant ce schéma produira des tableaux compatibles.

Aperçu

Chaque tableau se trouve à l'intérieur d'un bloc de code avec l'identifiant fancy-kanban. Cela signifie :

Un tableau peut être intégré n'importe où dans une note, au milieu de texte, de liens et d'autres contenus
Une note peut contenir zéro, un ou plusieurs tableaux
Un fichier constitué d'un seul bloc de tableau est un fichier de tableau autonome
Sans le plugin installé, le bloc s'affiche comme un bloc de code non stylisé — le texte brut reste entièrement lisible

Le bloc contient deux sections séparées par --- :

Une section de configuration (de type YAML) définissant les champs, le workflow et les options d'affichage
Un tableau Markdown contenant les lignes de données

Exemple Complet

```fancy-kanban
---
title: Mon Tableau
fields:
  - name: titre,       type: Texte,     label: Titre
  - name: statut,      type: Sélection, options: en_attente|en_cours|terminé, label: Statut, default: en_attente
  - name: responsable, type: Texte,     label: Responsable
  - name: date_début,  type: Date,     label: Date de début
  - name: notes,       type: ZoneTexte, label: Notes
  - name: effort,      type: Nombre,   label: Effort
  - name: docs,        type: Lien,     label: Docs
  - name: équipe,      type: Sélection, options: frontend|backend, label: Équipe
card_fields: responsable, effort
lanes: équipe
workflow: en_attente→en_cours, en_attente→terminé, en_cours→terminé, en_cours→en_attente, terminé→en_cours, terminé→en_attente
---

| _id    | Titre          | Statut     | Responsable | Date de début | Notes                        | Effort | Docs                  | Équipe   |
|--------|----------------|------------|-------------|---------------|------------------------------|--------|-----------------------|----------|
| x7k2a1 | Corriger bug login | en_attente | Alice       | 2026-01-15    | Nécessite investigation      | 3      |                       | backend  |
| m3p9b2 | Refactorisation authentification | en_cours | Bob         |              | Contenu multi-ligne\<br/> ici | 5      | design.md             | backend  |
| q1r4c3 | Configurer CI  | terminé    |             | 2026-01-01    |                              | 1      | setup.md\|guide.md | frontend |
```

Structure du Bloc

Le bloc de code contient exactement deux sections divisées par une ligne --- :

```fancy-kanban
---
{config}
---
{tableau Markdown}


Tout ce qui se trouve avant le premier `---` est ignoré (réservé pour une utilisation future). Tout ce qui se trouve entre les deux lignes `---` est la configuration. Tout ce qui se trouve après le deuxième `---` est le tableau.

## Section de Configuration

Paires clé-valeur de type YAML. Analysé ligne par ligne.

### Clés

| Clé | Requis | Défaut | Description |
|-----|--------|--------|-------------|
| `title` | oui | — | Nom lisible du tableau |
| `fields` | oui | — | Liste des définitions de champs (voir ci-dessous) |
| `version` | non | `1` | Version du format écrite par le plugin ; les tableaux avec une version supérieure à celle supportée par le plugin actuel s'ouvrent en mode lecture seule |
| `workflow` | non | toutes les transitions autorisées | Paires `de→vers` séparées par des virgules |
| `lanes` | non | aucune | Nom du champ à utiliser comme dimension de regroupement par couloir |
| `card_title` | non | détection auto | Nom du champ à utiliser comme titre de la carte ; définir sur une chaîne vide pour n'afficher aucun titre |
| `card_fields` | non | aucun | Liste ordonnée et séparée par des virgules des champs secondaires à afficher sous le titre de la carte |
| `card_labels` | non | `true` | Définir sur `false` pour masquer le préfixe du libellé sur les champs secondaires de la carte |
| `card_limit` | non | `0` (pas de limite) | Nombre maximum de cartes affichées par colonne ; les cartes au-delà de ce nombre sont masquées derrière un bouton « Afficher plus » |

### `card_title`

```yaml
card_title: résumé

Contrôle quel champ est rendu comme titre de la carte :

Absent (par défaut) : le premier champ qui n'est ni _id ni un champ de colonne est utilisé automatiquement
Défini sur un nom de champ : la valeur de ce champ apparaît comme titre
Défini sur une chaîne vide (card_title: ) : aucun titre n'est affiché ; la carte affiche uniquement les champs secondaires

`card_fields`

card_fields: priorité, échéance, docs

Une liste ordonnée, séparée par des virgules, des noms de champs secondaires à afficher sous le titre de la carte. Ceux-ci apparaissent comme des lignes étiquetées en dessous du titre.

Comportement par défaut : lorsque card_fields est absent, la carte affiche uniquement le champ du titre. Les tableaux existants sans clé card_fields ne sont pas affectés.

Noms inconnus : les noms de champs qui ne correspondent à aucun champ défini sont ignorés silencieusement lors du rendu. La suppression d'un champ de fields: le masque automatiquement de la face de la carte sans erreur d'analyse.

Champs de type Lien : lorsqu'un champ Lien est inclus dans card_fields, ses éléments sont rendus comme une liste horizontale de liens cliquables sur la face de la carte. Les chemins de coffre s'ouvrent dans un nouvel onglet ; les URI externes s'ouvrent dans le navigateur.

`card_labels`

card_labels: false

Lorsqu'il est défini sur false, le préfixe du libellé est omis des lignes de champs secondaires sur la face de la carte — seule la valeur est affichée. La valeur par défaut est true (libellés visibles). La clé n'est écrite dans la configuration que lorsque sa valeur est false.

`card_limit`

card_limit: 5

Lorsqu'il est défini sur un entier positif, chaque colonne affiche au maximum ce nombre de cartes. Les cartes au-delà de la limite sont masquées et un bouton Afficher plus (N) apparaît en bas de la colonne. Cliquer dessus révèle toutes les cartes restantes sans recharger le tableau. Définir card_limit: 0 ou omettre la clé désactive complètement la limitation.

Ceci est particulièrement utile pour les tableaux où la colonne terminé accumule de nombreuses cartes terminées au fil du temps — les cartes les plus récemment ajoutées restent visibles en un coup d'œil, tandis que l'historique plus ancien s'efface.

`lanes`

Lorsqu'il est défini sur un nom de champ (doit être un champ Sélection), le tableau s'affiche comme une matrice :

Colonnes — pilotées par l'ordre des options du champ statut
Lignes de couloir — pilotées par l'ordre des options du champ lanes

Les cartes sans valeur pour le champ lanes apparaissent dans un pseudo-couloir Non attribué en bas. Changer lanes est uniquement un changement de configuration d'affichage — aucune donnée de ligne n'est affectée.

Définitions de Champs

Chaque entrée dans la liste fields est un ensemble de paires clé: valeur séparées par des virgules sur une seule ligne, précédé de - :

fields:
  - name: titre, type: Texte, label: Titre
  - name: statut, type: Sélection, options: en_attente|en_cours|terminé, label: Statut, default: en_attente

Convention d'ordre des champs : listez titre en premier, puis statut, puis les champs supplémentaires. L'ordre des colonnes du tableau dans la section des données reflète l'ordre de définition des champs, et le titre de carte détecté automatiquement correspond au premier champ qui n'est ni _id ni un champ de colonne — donc placer titre en premier garantit une résolution prévisible du titre sans avoir besoin d'une clé card_title explicite.

Propriétés des Champs

Propriété	Requis	Description
`name`	oui	Identifiant interne. Minuscules, underscores pour les espaces.
`type`	oui	L'un des : `Texte`, `ZoneTexte`, `Date`, `Nombre`, `Sélection`, `Lien`
`label`	oui	En-tête de colonne lisible. Doit correspondre exactement à l'en-tête du tableau Markdown.
`options`	Sélection uniquement	Liste de valeurs autorisées séparées par des barres verticales (`\|`)
`colors`	Sélection, optionnel	Paires `nom=hex` séparées par des barres verticales assignant une couleur de fond à chaque option (par exemple `Haute=#e74c3c\|Basse=#27ae60`). Les options sans entrée s'affichent en texte brut.
`default`	non	Valeur par défaut pour les nouvelles cartes

Types de Champs

Type	Format de Stockage	Description
`Texte`	Chaîne simple	Texte sur une seule ligne
`ZoneTexte`	Chaîne avec `<br>` pour les retours à la ligne	Texte multiligne
`Date`	`AAAA-MM-JJ`	Date calendaire
`Nombre`	Chaîne entière ou décimale	Valeur numérique
`Sélection`	Une des valeurs des `options`	Choix contraint ; les options peuvent porter des couleurs hexadécimales via la propriété `colors`
`Lien`	Liste de chemins ou d'URI séparés par `<br>`	Chemins relatifs à la racine du coffre (`notes/doc.pdf`) ou URI externes (`https://…`, `ftp://…`, `mailto:…`)

Noms de Champs Spéciaux

Nom	Rôle
`titre`	Champ d'affichage principal. Doit être listé en premier dans `fields:`. Utilisé comme titre de carte détecté automatiquement lorsque `card_title` n'est pas défini.
`statut`	Requis. Champ de colonne Kanban. Doit être `type: Sélection`. Les cartes sont regroupées en colonnes selon cette valeur. L'ordre des colonnes suit l'ordre des `options`.

Tous les autres champs sont secondaires — affichés comme métadonnées de carte lorsqu'ils sont listés dans card_fields.

Identité des Éléments

Chaque carte a un ID caché stable stocké dans une colonne _id dans le tableau Markdown. L'interface utilisateur n'affiche jamais cette colonne.

Généré lors de la création de la carte : chaîne alphanumérique aléatoire courte (par exemple 8 caractères : x7k2a1b3)
Préservé à travers tous les aller-retours de sérialisation
Survit au réordonnancement, au glisser-déposer et aux renommages de champs
Utilisé en interne pour toutes les opérations sur les cartes (déplacer, éditer, supprimer)

Parce que l'identité est basée sur l'ID et non dérivée du contenu, renommer le titre d'une carte n'a aucun effet sur son identité.

Workflow

Définit les transitions de statut autorisées dans l'interface utilisateur :

workflow: en_attente→en_cours, en_attente→terminé, en_cours→terminé, en_cours→en_attente, terminé→en_cours, terminé→en_attente

Liste de paires de→vers séparées par des virgules (flèche : →, U+2192)
Si workflow est omis, toutes les transitions entre les options de statut sont autorisées
Utilisé pour contraindre les choix de l'interface utilisateur (par exemple un menu « Déplacer vers » n'affiche que les cibles valides)
Les modifications manuelles du tableau brut contournent la validation du workflow, car il s'agit de texte brut

Modèles de Tableau

Lors de la création d'un nouveau tableau, un ensemble de modèles prédéfinis fournit des ensembles d'options de statut courants. Les modèles ne pré-remplissent que les options du champ statut et le workflow — tous les autres champs sont ajoutés par l'utilisateur.

Modèle	Options de statut	Workflow par défaut
Basique	`en_attente \| en_cours \| terminé`	Toutes les transitions
Logiciel	`backlog \| à faire \| en cours \| revue \| terminé`	Avant + un pas en arrière
Contenu	`idée \| brouillon \| revue \| publié`	Avant uniquement
Projet	`planification \| actif \| bloqué \| terminé`	Toutes sauf → planification
Personnalisé	Défini par l'utilisateur	Défini par l'utilisateur

La sélection de Personnalisé ouvre un éditeur libre pour les options de statut et les transitions de workflow.

Tableau Markdown

Le tableau apparaît immédiatement après la fermeture --- de la section de configuration.

Structure

| _id    | En-tête1 | En-tête2 |
|--------|----------|----------|
| abc123 | valeur   | valeur   |

Ligne d'en-tête — la première colonne est toujours _id ; les colonnes restantes sont les libellés des champs dans l'ordre de définition du schéma
Ligne de séparation — séparateur de tableau Markdown standard
Lignes de données — une ligne par carte ; la cellule _id contient l'ID stable de la carte

Règles

L'ordre des colonnes dans le tableau doit correspondre à l'ordre de définition des champs (après _id)
Les cellules vides sont valides (valeur du champ = chaîne vide)
L'ordre des lignes dans un groupe de statut est l'ordre d'affichage
Un tableau vide (en-tête + séparation, aucune ligne de données) est valide
La colonne _id est toujours en premier et n'est jamais affichée dans le tableau rendu

Échappement

Caractère dans la valeur	Échappé en
`\|` (barre verticale)	`\|` (barre verticale précédée d'un antislash)
Nouvelle ligne	`<br>`
Retour chariot	`<br>`

Lors de la lecture : \| → |, <br> → nouvelle ligne. Lors de l'écriture : | → \|, toute nouvelle ligne → <br>.

Algorithme d'Analyse

Extraire la chaîne brute entre les délimiteurs d'ouverture et de fermeture du bloc fancy-kanban
Diviser sur la première ligne --- pour localiser le début de la section de configuration
Diviser sur la deuxième ligne --- pour séparer la configuration du tableau
Analyser la configuration ligne par ligne : extraire title, version, fields, workflow, lanes, card_title, card_fields, card_labels, card_limit
Pour fields, collecter les lignes commençant par - et analyser chacune comme des paires clé: valeur séparées par des virgules ; colors est décodé comme des jetons nom=hex séparés par des barres verticales
Trouver les lignes du tableau dans le corps (lignes commençant par |)
La première ligne du tableau est la ligne d'en-tête — extraire les libellés des colonnes ; _id est toujours en premier
Mapper les libellés d'en-tête restants aux noms de champs via une recherche de libellé insensible à la casse
Analyser chaque ligne de données : diviser sur les | non échappés, couper les cellules, déséchapper \| et <br>
La première cellule de chaque ligne de données est l'_id de la carte
Regrouper les cartes par valeur du champ statut, en initialisant les groupes dans l'ordre des options

Réconciliation du schéma (appliquée après l'analyse) :

Champs présents dans le schéma mais manquants dans les données d'une carte : compléter avec la valeur default du champ (ou chaîne vide)
Champs présents dans les données de la carte mais supprimés du schéma : préserver comme données cachées orphelines (non supprimées)

Algorithme d'Écriture

Reconstruire la section de configuration à partir du schéma actuel (préserver le formatage original dans la mesure du possible)
Générer la ligne d'en-tête : _id en premier, puis les libellés des champs dans l'ordre de définition du schéma
Générer la ligne de séparation
Générer une ligne de données par carte : _id en premier, puis les valeurs des champs dans l'ordre du schéma, avec les barres verticales et les retours à la ligne échappés
Générer un nouvel _id de carte à l'aide d'une chaîne alphanumérique aléatoire si la carte n'a pas d'ID existant
Reconstruire le bloc complet : délimiteur d'ouverture, configuration, ---, ligne vide, tableau, délimiteur de fermeture

Principe de réécriture : seule la plage de texte du bloc affecté est corrigée dans le fichier source — le contenu environnant n'est jamais réécrit.

Tableau Minimal Viable

```fancy-kanban
---
title: Mon Tableau
fields:
  - name: titre, type: Texte, label: Titre
  - name: statut, type: Sélection, options: en_attente|en_cours|terminé, label: Statut, default: en_attente
workflow: en_attente→en_cours, en_attente→terminé, en_cours→terminé, en_cours→en_attente, terminé→en_cours, terminé→en_attente
---

| _id | Titre | Statut |
|-----|-------|--------|


## Notes de Compatibilité

- Sans le plugin, le bloc s'affiche comme un bloc de code simple — toutes les données sont toujours visibles sous forme de texte brut
- Le tableau Markdown à l'intérieur du bloc est un Markdown valide et lisible dans n'importe quel éditeur de texte
- La section de configuration suit les conventions YAML familières aux générateurs de sites statiques et aux applications de prise de notes
- La suppression du plugin laisse toutes les données intactes et récupérables

## Fonctionnalités Obsolètes

Voir [docs/obsolescences.md](obsolescences.md) pour la liste complète des fonctionnalités supprimées et leurs équivalents modernes.

robertoallende/fancy-kanban

Qu'est-ce que fancy-kanban ?

Demander à votre IA préférée

Documentation