Mermaid ASCII : rendu de diagrammes Mermaid dans le terminal

 (github.com/lukilabs)
16 points par GN⁺ 2026-01-30 | 1 commentaires | Partager sur WhatsApp
  • beautiful-mermaid est un outil ultra-rapide basé sur TypeScript pour rendre des diagrammes Mermaid en SVG ou en art ASCII
  • Prend en charge 5 types de diagrammes (Flowchart, State, Sequence, Class, ER) et fonctionne à la fois dans le terminal et dans le navigateur
  • Grâce à 15 thèmes intégrés et à la compatibilité Shiki, il est possible d’appliquer directement des thèmes VS Code
  • Le mode Mono fournit une représentation visuelle cohérente avec seulement deux couleurs, tandis que les propriétés CSS personnalisées permettent un changement de thème en temps réel
  • Son importance ressort comme outil léger et sans dépendances pour visualiser les flux de données et la structure des systèmes dans des environnements de programmation assistée par IA

Vue d’ensemble

  • beautiful-mermaid est un outil qui rend des diagrammes Mermaid en SVG ou en texte ASCII/Unicode
    • Fonctionne sans dépendance au DOM et prend en charge un rendu ultra-rapide (plus de 100 diagrammes en moins de 500 ms)
    • Développé par l’équipe Craft pour Craft Agents
  • Portage en TypeScript de Mermaid-ascii (projet basé sur Go), avec des fonctionnalités étendues
    • Ajout de la prise en charge des diagrammes Sequence, Class et ER
    • Inclut les caractères de boîte Unicode, ainsi que des réglages d’espacement et de padding

Fonctionnalités principales

  • Types de diagrammes pris en charge : Flowchart, State, Sequence, Class, ER
  • Formats de sortie : SVG (pour les interfaces riches), ASCII/Unicode (pour le terminal)
  • Système de thèmes
    • 15 thèmes intégrés disponibles (tokyo-night, dracula, nord, github-dark, etc.)
    • Mode Mono : toutes les couleurs sont automatiquement dérivées à partir de deux couleurs seulement, l’arrière-plan (bg) et l’avant-plan (fg)
    • Mode enrichi : possibilité de définir des couleurs optionnelles comme accent, muted, surface, border, etc.
    • Prend en charge un basculement en temps réel basé sur les propriétés CSS personnalisées
  • Intégration Shiki
    • Mappage automatique des couleurs des thèmes VS Code vers les couleurs du diagramme
    • La fonction fromShikiTheme() permet d’extraire bg, fg, accent, etc.

Installation et utilisation

  • Commandes d’installation
    • npm install beautiful-mermaid ou bun add beautiful-mermaid, pnpm add beautiful-mermaid
  • Exemple de rendu SVG 
    import { renderMermaid } from 'beautiful-mermaid'
const svg = await renderMermaid(`graph TD; A-->B;`)
  • Exemple de rendu ASCII 
    import { renderMermaidAscii } from 'beautiful-mermaid'
const ascii = renderMermaidAscii(`graph LR; A --> B --> C`)
  • Utilisation dans le navigateur
    • Chargement direct possible via une balise <script> depuis un CDN (unpkg, jsDelivr)
    • Accès à renderMermaid, renderMermaidAscii, THEMES, etc. depuis l’objet global beautifulMermaid

Sortie ASCII et options

  • Prise en charge du mode Unicode (par défaut) et du mode ASCII pur
  • Options disponibles
    • useAscii : activer ou non ASCII
    • paddingX, paddingY : espacement entre les nœuds
    • boxBorderPadding : marge intérieure des nœuds
  • Exemple de sortie 
    ┌───┐     ┌───┐
│ A │────►│ B │
└───┘     └───┘

Résumé de l’API

  • renderMermaid(text, options?) : rend un diagramme Mermaid en SVG
    • Options : bg, fg, accent, muted, surface, border, font, transparent
  • renderMermaidAscii(text, options?) : rendu en texte ASCII/Unicode
  • fromShikiTheme(theme) : extrait les couleurs d’un thème Shiki
  • THEMES : objet contenant 15 thèmes intégrés
  • DEFAULTS : couleurs par défaut (#FFFFFF, #27272A)

Licence et création

  • Licence MIT
  • Créé par l’équipe Craft
  • Moteur ASCII basé sur mermaid-ascii d’Alexander Grooff

Portée technique

  • Dans les environnements d’assistant de code IA, il permet de visualiser instantanément des diagrammes dans le terminal ou dans une interface de chat
  • Sa structure légère, rapide et sans dépendances le rend très utile aussi bien pour les outils CLI que pour les environnements serveur
  • Son extensibilité thématique et sa compatibilité améliorent l’expérience développeur

À lire aussi

1 commentaires

 
GN⁺ 2026-01-30
Commentaires sur Hacker News

  • Le projet basé sur la bibliothèque Go mermaid-ascii créée par Alexander Grooff est vraiment génial
    J’y ai toutefois trouvé un bug où l’arête "start" n’est pas rendue
    Les tests ont été effectués sur agents.craft.do/mermaid

  • Je ne comprends pas bien pourquoi les diagrammes ASCII reviennent à la mode en ce moment
    Mermaid et PlantUML sont déjà basés sur du texte, et la plupart des utilisateurs veulent surtout des diagrammes standards agréables à lire pour les humains plutôt que pour les machines
    ASCII est limité aux caractères imprimables, donc c’est moins expressif et difficile à standardiser

    • Cela dépend du contexte. Par exemple, dans un README ou une sortie CLI, quand le rendu Mermaid est impossible, l’ASCII est souvent le meilleur choix en matière de lisibilité
    • On peut mettre des diagrammes ASCII dans les commentaires du code. Ils s’affichent aussi très bien dans des outils orientés terminal comme Claude Code
    • Plutôt que de dire que « l’ASCII ne sert à rien », il peut au contraire être utile dans des workflows centrés sur le texte (par ex. Org Mode, gestion de dépôts Git)
      car cela évite d’avoir à gérer des fichiers image ou des configurations complexes comme Git LFS
    • L’absence de moteur de rendu est un avantage. On peut les lire directement sous une forme déjà « rendue » dans un document Markdown ou dans le code source
    • Comme beaucoup de développeurs et d’agents de code travaillent surtout avec Markdown et dans des environnements CLI, cette approche ASCII est assez naturelle

  • J’adore vraiment les diagrammes ASCII
    Que ce soit dans un terminal avec cat ou rendus sur un site web, ils gardent le même rendu sympa
    Avec une bonne police à chasse fixe, c’est aussi très propre visuellement
    Je recommande aussi Monodraw, une application de création de diagrammes ASCII

    • ^Unicode
    • J’aime particulièrement le fait qu’on puisse mettre un diagramme en haut du code source

  • Le véritable moteur de rendu Mermaid ASCII provient en fait du projet AlexanderGrooff/mermaid-ascii
    Ce projet l’a converti en TypeScript et a ajouté son propre thème

    • En réalité, il aurait peut-être suffi de packager mermaid-ascii en WASM
      L’algorithme principal est presque une conversion 1:1, donc Claude aurait probablement pu le porter en TS en moins d’une heure
      On peut comparer le code Go et le code TS
    • Merci pour le crédit
    • Comme c’est basé sur Go, pas besoin de faire de blague sur la gestion de paquets. Je compte l’intégrer à mon débogueur
    • Quelqu’un a fait remarquer que l’IA avait peut-être simplement copié tout le projet et changé le nom
    • Le lien d’origine a été corrigé. L’auteur de la soumission semble l’avoir posté de bonne foi

  • Mermaid attire l’attention, mais Kroki(kroki.io) prend en charge une bien plus grande variété de formats de diagrammes
    Cela inclut pratiquement tous les diagrammes textuels comme BlockDiag, BPMN, C4, D2, DBML, Excalidraw, GraphViz, etc.
    Mon éditeur Markdown KeenWrite(keenwrite.com) intègre Kroki comme service, donc lorsqu’un nouveau format est ajouté, il devient automatiquement disponible
    Comme Mermaid utilise <foreignObject>, son rendu est difficile dans la plupart des bibliothèques

    • Comparer MermaidJS et Kroki, c’est un peu comme comparer PDF.js et Adobe Acrobat
      MermaidJS s’exécute rapidement et localement dans une page web, tandis que Kroki dépend d’un service externe
      Si l’on n’a pas besoin de diagrammes complexes, Mermaid est le choix le plus simple
    • J’avais déjà créé un outil appelé phart pour rendre des DAG NetworkX en ASCII
      Le README d’exemple montre divers rendus, dont des graphes d’échecs
    • Au début, je trouvais le design de Kroki peu convaincant à cause de trop d’ombres et de polices déformées, mais j’ai compris ensuite que c’était une erreur de ma part
      Je trouve quand même le style par défaut de Mermaid plus propre
      Cela dit, KeenWrite a l’air vraiment excellent

  • Il existe aussi Diagon, un outil qui convertit du texte en diagrammes ASCII
    J’ai aussi une liste d’outils texte→diagramme, mais il n’y a pas beaucoup d’outils de conversion texte→ASCII

    • Quelqu’un a remercié pour cette bonne liste

  • Pour lancer la démo en direct, il semble qu’il faille télécharger la plateforme d’agents IA
    C’est dommage qu’on ne puisse pas l’essayer directement sans installation

    • Ce serait bien que les développeurs créent une démo purement cliente sur GitHub Pages
      Vu la structure du projet, cela semble tout à fait faisable

  • Il existe une fonctionnalité appelée “Subgraph Direction Override”, qui permet de définir une direction différente pour les sous-graphes
    Avec ça, on peut imiter des diagrammes en couloirs (swim lanes) que Mermaid ne prenait pas en charge

  • Selkie, que j’ai créé, est un projet expérimental qui implémente entièrement en Rust un parseur et un moteur de rendu Mermaid
    Je m’en servais pour tester jusqu’où on pouvait aller avec Claude Code, et les résultats sont surprenants
    On peut l’exécuter directement dans le Playground
    Avec la prise en charge du terminal Kitty, il est même possible d’afficher les diagrammes directement dans le terminal
    Je vais bientôt publier un billet de blog sur tout le processus

  • Ce projet est vraiment génial, et sa synergie avec Claude Code est aussi impressionnante
    J’ai mené un projet similaire, mais axé sur l’exploration de code interactive plutôt que sur l’ASCII
    Je l’ai conçu pour aider la compréhension humaine, en utilisant D2, avec une prise en charge de Mermaid en préparation
    J’aimerais avoir des avis sur ce qui a le plus de valeur : l’interactivité pour les humains, ou le contexte pour les agents
    Lien du projet