Diagrammes de Gantt Mermaid : syntaxe, pièges et aller-retour vers un vrai éditeur

La syntaxe en une passe

Un bloc s’ouvre par le mot-clé gantt, suivi de quelques lignes d’en-tête, puis de titres section sous lesquels viennent les lignes de tâches. L’indentation est une convention de lisibilité, pas une règle de grammaire : Mermaid lit aussi bien un fichier aligné qu’un fichier collé de travers.

Une ligne de tâche, c’est un nom, deux-points, puis des champs séparés par des virgules :

Nom de la tâche :marqueur, id, début, durée

• Marqueurs, au choix done, active, crit, milestone, dans n’importe quel ordre, et vous pouvez les cumuler. Facultatifs.
• id, un mot simple, sans espace ni ponctuation, nécessaire seulement si une autre tâche s’y réfère.
• début, une date, ou after unId, ou rien du tout pour enchaîner sur la tâche précédente.
• durée, 5d, 2w, ou une seconde date absolue qui tient lieu de fin.

Les lignes d’en-tête à connaître : dateFormat (comment sont écrites les dates dans votre fichier), excludes weekends, title, et axisFormat (le libellé de l’axe, en codes de type strftime). Les champs sont reconnus à leur forme plutôt qu’à leur position stricte, ce qui explique que :done, audit, 2026-03-02, 5d et :audit, done, 2026-03-02, 5d donnent le même résultat, commode à l’écriture, déroutant à la relecture.

Un exemple complet à coller dans un README

Voici un bloc valide et réaliste, tiré d’un cas courant : la migration de l’API publique d’une v1 vers une v2 chez Sogecom, éditeur logiciel installé à Villeurbanne. Claire Vasseur, tech lead de l’équipe plateforme, tient ce planning dans le README du dépôt api-gateway pour qu’il soit relu en revue de code comme le reste. L’exemple utilise des sections, des dates absolues, des chaînes de after, tous les marqueurs, un jalon et l’exclusion des week-ends.

gantt
  title Migration API v2, Sogecom
  dateFormat YYYY-MM-DD
  axisFormat %d %b
  excludes weekends

  section Cadrage
  Audit des endpoints v1   :done, audit, 2026-03-02, 5d
  Contrat OpenAPI          :done, spec, after audit, 4d
  Revue de code du contrat :active, revue, after spec, 2d

  section Développement
  Service d’authentification :crit, auth, after revue, 10d
  Endpoints ressources       :endp, after auth, 12d
  Régénération du SDK client :sdk, after endp, 3d

  section Bascule
  Recette sur préproduction :recette, after sdk, 5d
  Bêta publique             :milestone, beta, 2026-05-04, 0d
  Arrêt de la v1            :arret, after beta, 2w

Référence des champs d’une ligne de tâche

Tous les champs et marqueurs, ce qu’ils font, et à quoi ils ressemblent en pratique.

Une remarque sur excludes et le calendrier français : les jours fériés se déclarent un par un, et les ponts n’existent pas pour Mermaid. Si l’équipe ferme le vendredi de l’Ascension ou lève le pied en août, écrivez-le, sans quoi le diagramme promet du travail des jours où personne ne travaille.

Quatre choses qui vous piégeront

1. Les durées incluent le jour de début. 5d à partir du lundi 5 court jusqu’au vendredi 9, pas jusqu’au 10. Une erreur d’un jour ici décale toutes les tâches du fichier et s’affiche pourtant parfaitement, ce qui est le pire mode de défaillance possible : rien n’a l’air cassé, la revue de code passe, et le planning est faux d’un jour par tâche.

2. after combiné à excludes weekends, c’est là que sont les vrais bugs. Si un prédécesseur finit un vendredi, son successeur démarre le lundi, pas le samedi. Tout outil qui résout after en ajoutant un jour calendaire placera discrètement des tâches le week-end dans un fichier qui l’interdit explicitement, et toutes les dates en aval dérivent à partir de là. Le nôtre l’a fait, brièvement. Le correctif fait passer le calcul par le calendrier ouvré, pour que l’import concorde avec ce que Mermaid dessine ; et le test qui garde ce comportement vérifie une propriété plutôt que des dates précises : aucune date calculée, de début comme de fin, ne doit tomber un jour exclu. Les dates que vous avez tapées à la main, elles, restent exactement où vous les avez posées, week-end ou pas, déplacer en silence la date explicite d’un auteur, c’est la mauvaise façon de rendre service.

3. Il n’y a aucun échappement. Les deux-points ouvrent la liste des champs et la virgule les sépare : une tâche nommée Phase 2 : conception, revue devient une tâche « Phase 2 » suivie de champs incompréhensibles. Bannissez deux-points, virgules et points-virgules des noms de tâches. À l’export, nous remplaçons ces caractères par des espaces plutôt que d’écrire une ligne qui refusera de s’analyser chez le lecteur.

4. Une durée illisible devient zéro, en silence. Écrivez 3dd et vous obtenez une barre de longueur nulle plutôt qu’une erreur. Après une modification en masse, un chercher-remplacer sur trente lignes, typiquement, relisez le rendu à la recherche de tâches devenues invisibles.

Les limites d’un format de diagramme

Mermaid gantt est un langage de rendu, pas un moteur de planification, et la différence saute aux yeux dès que vous attendez du diagramme qu’il réponde à une question plutôt qu’illustrer une réponse déjà connue.

• Pas de ressources. Aucun champ pour dire qui fait le travail, aucun coût, aucune charge, aucune unité. Vous ne pouvez pas sur-affecter quelqu’un dans Mermaid, pour la bonne raison que Mermaid ignore que quelqu’un existe.
• Ni marge, ni chemin critique calculé. crit est une couleur que vous appliquez à la main. Rien ne parcourt le graphe des antériorités, ne calcule les dates au plus tôt et au plus tard, ne vous dit quelle chaîne pilote la date de fin. Un diagramme où toutes les barres portent crit est aussi valide qu’un diagramme où aucune ne le porte.
• Pas de référence. Nulle part où consigner ce que le plan annonçait le mois dernier : donc aucun écart à montrer, aucune dérive à mesurer.
• Uniquement du Fin-Début. after est un lien FD sans décalage. Le Début-Début, le Fin-Fin, le Début-Fin et tout décalage, positif ou négatif, n’ont nulle part où aller. Les vrais plannings sont pleins de « la recette démarre trois jours après le début du développement » ; en Mermaid, cela devient une date en dur, et le lien a disparu.
• Pas de pourcentage d’avancement. Une tâche à 40 % et une tâche à 90 % sont toutes deux simplement active.
• Sections à plat. Aucun groupe imbriqué : une décomposition à plus d’un niveau s’aplatit à l’import.

Rien de tout cela n’en fait un mauvais format. Cela en fait un format de publication : excellent pour montrer un planning, inutilisable pour en déduire un. C’est précisément pourquoi l’aller-retour compte.

Modifier visuellement, puis recoller le texte

Beaucoup d’outils affichent du Mermaid. Ce qui manquait, c’est l’autre sens : déplacer des barres et récupérer la syntaxe. Voici la manipulation complète, avec les libellés réels de l’application.

1. Ouvrez l’éditeur et cliquez sur ✨ Coller vers Gantt. Collez-y votre bloc, qu’il vienne d’un fichier .mmd ou d’un .md contenant un bloc délimité : la détection se fait sur le contenu, pas sur l’extension.
2. Validez. Le message Tâches importées depuis Mermaid : {n} vous confirme le nombre de lignes reprises, comparez-le au nombre de tâches de votre fichier avant d’aller plus loin.
3. Vérifiez le calendrier. Si le fichier déclarait excludes weekends, ouvrez Calendrier et confirmez que les jours ouvrés correspondent ; ajoutez-y les jours fériés que Mermaid ne connaît pas.
4. Déplacez, reliez et redatez comme sur n’importe quel autre planning. Le champ Après (prédécesseurs) du panneau de tâche reprend ce que les after ont produit ; c’est là que vous ajoutez les liens Début-Début ou les décalages que le format ne savait pas écrire.
5. Activez Chemin critique : la légende « hachuré = chemin critique » vous montre la chaîne réellement calculée. Utilisez Replanifier si vous voulez compacter les tâches sur leurs dates au plus tôt.
6. Enfin ⬇ Exporter › 🧜 Mermaid gantt (texte). La fenêtre Mermaid gantt propose Copier dans le presse-papiers ou Télécharger le .mmd. Recollez dans le README, ouvrez la revue de code, commitez le diff.

L’aller-retour perd de l’information, mais de façon connue et sans surprise. À l’export, un avancement de 100 % devient done et toute valeur de 1 à 99 % devient active ; à l’import, active revient à 50 %, une estimation qu’un avertissement vous signale plutôt que de vous la laisser découvrir dans un rapport d’avancement. Les liens qui ne peuvent pas s’écrire en after, tout ce qui comporte un décalage, toute relation Début-Début, Fin-Fin ou Début-Fin, retombent sur des dates absolues, qui restent justes même si elles cessent d’être maintenables.

Une asymétrie assumée, parce que ce n’est pas un défaut : crit est écrit à l’export mais jamais lu à l’import. À la sortie, le marqueur est dérivé, l’éditeur a calculé le chemin critique à partir du graphe des antériorités, la mention est donc vraie au moment où elle est écrite. À l’entrée, ce n’est plus qu’un mot tapé par quelqu’un dans un fichier peut-être vieux de plusieurs semaines, et lui faire confiance reviendrait à colorer en rouge une chaîne qui n’est pas critique. Il est donc écrit puis ignoré : marquer une tâche crit dans votre fichier et l’importer ne la rend pas critique, et un simple aller-retour recalculera la criticité à partir des liens. Le chemin critique que vous voyez après un import a été recalculé, jamais recopié, le même principe que dans le calcul du chemin critique.

Effet de bord appréciable pour qui rédige ses plannings avec un LLM : demandez de la syntaxe Mermaid gantt, collez la réponse dans ✨ Coller vers Gantt, et vous obtenez un planning modifiable dont le chemin critique est calculé, sans clé d’API, sans serveur, et sans que le fichier quitte votre machine.

Questions fréquentes

Modèles qui utilisent ceci

• Gestion de projet

À lire aussi

• Les quatre types de liens
• Le chemin critique
• Qu’est-ce qu’un diagramme de Gantt ?
• Retour aux guides

Cet article est également disponible en anglais.