Kanban.md
Un tableau Kanban dont chaque carte est un fichier Markdown avec un front matter YAML. Les fichiers restent la seule source de vérité : lisibles, versionnables dans git, modifiables à la main. L'extension ne stocke rien d'autre.
Fonctionnalités
- Tableau : une colonne par statut, cartes déplaçables par glisser-déposer (souris ou clavier : Espace, flèches, Espace). Déplacer une carte ne modifie que
status et order dans son fichier ; commentaires, ordre des clés et fins de ligne sont préservés.
- Panneau de détail à droite du tableau : un clic sur une carte l'affiche, un autre clic la remplace.
- Visualisation : Markdown rendu avec images locales, diagrammes Mermaid (qui suivent le thème clair/sombre), code coloré, cases à cocher cliquables.
- Formulaire de métadonnées généré depuis la configuration ; chaque changement est sauvegardé immédiatement.
- Modifier : le corps passe en Markdown brut dans le même panneau.
Ctrl/Cmd+S (ou « Enregistrer ») sauvegarde et revient à la visualisation.
- Images : coller une capture depuis le presse-papier, déposer un fichier, ou choisir une image existante. Les images vont dans un dossier commun, sans doublon (même contenu = même fichier).
- Autocomplétion des liens : en tapant la destination d'un lien (juste après
](), un menu propose les images du dossier des assets pour un lien d'image, et les autres cartes puis les images pour un lien normal.
- Si le fichier change ailleurs pendant l'édition, un bandeau le signale et l'écrasement demande confirmation.
- Recherche et filtres : recherche plein texte (accents et casse ignorés, plusieurs mots) et un filtre par champ de
kanbanMd.fields (liste de choix, tags, texte avec suggestions, échéance, case à cocher). Les compteurs de colonne affichent « visibles/total ». On peut déplacer une carte même quand d'autres sont masquées.
- Ajout rapide : le « + » d'une colonne ouvre un champ en bas de la colonne.
Entrée crée la carte et laisse le champ ouvert pour enchaîner ; Ctrl/Cmd+Entrée crée et ouvre la carte ; Échap annule. Un modèle (kanbanMd.template) est appliqué s'il existe.
- Archivage : une carte archivée garde son fichier et son chemin, seule la clé
archived: true est ajoutée. Elle est masquée du tableau (bascule « Archives » pour la voir). On peut archiver toutes les cartes visibles d'une colonne (menu « ⋯ »).
- Annulation : supprimer une carte l'envoie à la corbeille sans confirmation et affiche un toast « Annuler » ;
Ctrl/Cmd+Z restaure le fichier octet pour octet. L'archivage est annulable de la même façon.
- Affichage : colonnes repliables (une carte peut être déposée sur une colonne repliée), mode compact, échéances relatives (« En retard de 3 j », « Demain », « Dans 5 j »). Ces préférences sont mémorisées par workspace et ne touchent jamais aux fichiers.
- Vue dans la barre d'activité : les colonnes, leur nombre de cartes et de retards, et les cartes de chaque colonne ; un clic ouvre la carte dans le tableau.
- Gestion des tags :
Kanban: Gérer les tags renomme (avec fusion sans doublon) ou supprime une valeur dans toutes les cartes, en ne réécrivant que la ligne concernée.
- Apparence soignée : cartes et colonnes sobres qui suivent le thème VS Code (clair, sombre, contraste élevé) ; référence de la carte (clé
idField, sinon nom du fichier), badge de priorité coloré, assigné, échéance, progression des cases ; barre d'outils avec filtres en listes déroulantes ; ligne « Ajouter une carte » en bas de colonne ; panneau de détail avec capsules de métadonnées.
- Disposition verticale : le bouton à droite de la barre d'outils empile les colonnes de haut en bas, avec les cartes en grille dans chaque colonne. Le choix est mémorisé par workspace.
- Mise à jour en direct : toute modification des fichiers (édition manuelle,
git pull…) se reflète sur le tableau.
Raccourcis clavier
Actifs quand le focus n'est pas dans un champ de saisie (sauf mention). ? affiche l'aide dans le tableau.
| Touche |
Action |
N |
Ajout rapide dans la colonne de la carte affichée (sinon la première colonne) |
/ ou Ctrl/Cmd+F |
Rechercher |
E |
Modifier la carte affichée |
Ctrl/Cmd+E |
Basculer visualisation ↔ édition (aussi dans le champ d'édition) |
Ctrl/Cmd+S |
Enregistrer l'édition en cours |
Suppr / Retour arrière |
Supprimer la carte sélectionnée (annulable) |
Ctrl/Cmd+Z |
Annuler la dernière action proposée par un toast |
Échap |
Ferme le menu ouvert, puis annule l'édition, puis vide la recherche, puis ferme le panneau |
Espace, flèches, Espace |
Déplacer une carte au clavier |
? |
Afficher l'aide des raccourcis |
Démarrage rapide
Ouvre un dossier dans VS Code et crée kanban/ma-premiere-carte.md :
---
title: Ma première carte
status: todo
order: 1
tags: [demo]
---
## Contexte
- [ ] Une tâche
Lance la commande Kanban: Ouvrir le tableau (ou l'icône dans la barre de titre d'un fichier Markdown).
Par défaut, les cartes sont les fichiers kanban/**/*.md. Les colonnes par défaut sont backlog, todo, in-progress et done.
| Clé |
Rôle |
status |
Colonne de la carte (champ configurable). Absent ou inconnu → colonne « Non classé ». |
order |
Position dans la colonne (nombre décimal). Écrit par l'extension lors des déplacements. |
title |
Titre affiché. Sinon : premier titre # H1 du corps, sinon le nom du fichier. |
| autres |
Définies par kanbanMd.fields (tags, assigné, priorité, échéance…). Les clés inconnues sont conservées telles quelles. |
Un YAML invalide n'empêche pas l'affichage : la carte reste dans sa colonne avec un avertissement, mais elle n'est pas déplaçable tant que le front matter n'est pas corrigé.
Commandes
| Commande |
Rôle |
Kanban: Ouvrir le tableau |
Ouvre (ou révèle) le tableau. |
Kanban: Nouvelle carte |
Choisit une colonne et un titre, crée la carte et l'affiche. |
Kanban: Insérer une image existante |
Choisit une image du dossier des assets (pendant l'édition d'une carte). |
Kanban: Gérer les tags |
Renomme (fusion possible) ou supprime une valeur de tag dans toutes les cartes. |
Réglages
Tout se règle dans les settings (kanbanMd.*), typiquement dans .vscode/settings.json du workspace.
| Réglage |
Défaut |
Rôle |
kanbanMd.cardsGlob |
kanban/**/*.md |
Fichiers qui sont des cartes. Les nouvelles cartes sont créées dans la partie fixe du glob. |
kanbanMd.excludeGlob |
**/{_template.md,node_modules/**} |
Fichiers exclus. |
kanbanMd.statusField |
status |
Clé du front matter qui désigne la colonne. |
kanbanMd.columns |
4 colonnes |
id, label et color (hex ou couleur de thème comme charts.blue) de chaque colonne. |
kanbanMd.fields |
titre, tags, assigné, priorité, échéance |
Champs du formulaire : text, number, date, select, tags, checkbox, avec required, suggest, options. |
kanbanMd.assetsFolder |
kanban/assets |
Dossier commun des images. |
kanbanMd.template |
null |
Fichier modèle des nouvelles cartes (jamais affiché comme carte). |
kanbanMd.archiveField |
archived |
Clé booléenne du front matter qui marque une carte archivée. |
kanbanMd.showCardId |
true |
Affiche la référence de chaque carte (tableau et panneau de détail). |
kanbanMd.idField |
id |
Clé du front matter utilisée comme référence ; à défaut, le nom du fichier sans extension. |
kanbanMd.newCardsAtTop |
false |
Crée les nouvelles cartes en haut de la colonne (et place la ligne « Ajouter une carte » en haut). |
"kanbanMd.columns": [
{ "id": "todo", "label": "À faire", "color": "charts.blue" },
{ "id": "done", "label": "Terminé", "color": "#3fb950" }
]
Les entrées de configuration invalides sont ignorées et signalées par un bandeau dans le tableau.
Limites connues
- Un seul tableau par workspace, et seul le premier dossier d'un workspace multi-dossiers est utilisé.
- Pas de limites WIP ni de couloirs (swimlanes) ; les filtres ne sont pas sauvegardés (ils repartent à vide à chaque ouverture).
- L'autocomplétion de liens ne propose que les images du dossier des assets et les cartes (pas les ancres de titres).
- Le panneau de détail a une largeur fixe.
- Le bundle de la webview est volumineux (~5,5 Mo, à cause de Mermaid) ; il ne se charge qu'à l'ouverture du tableau.
Développement
npm install
npm run build # typecheck + bundles
npm test # tests unitaires (vitest)
npm run test:integration # tests dans un vrai VS Code (VSCODE_EXECUTABLE_PATH=… pour utiliser une installation locale)
npm run package # produit le .vsix
F5 lance un Extension Development Host sur le dossier sample/. La spécification complète est dans SPEC.md.
Licence
MIT (voir le fichier LICENSE).
| |