oxdraw - un outil de diagrammes piloté par le code

• oxdraw est un outil de type « Diagram as Code » écrit en Rust, conçu pour éditer visuellement des diagrammes basés sur du code et les conserver sous une forme reproductible
• Les diagrammes sont écrits en syntaxe Mermaid, et une interface web permet d’ajuster par glisser-déposer la position des nœuds, les couleurs, les connexions, etc.
• Les modifications visuelles sont enregistrées sous forme de commentaires dans le fichier Mermaid, ce qui préserve la compatibilité avec les autres outils Mermaid
• Le projet se compose d’une CLI et d’un éditeur web basé sur React, avec prise en charge à la fois du rendu en ligne de commande et du mode d’édition en temps réel
• En combinant la productivité des diagrammes générés par le code et la liberté de l’édition visuelle, il attire l’attention comme alternative aux outils GUI comme Lucidchart

---

Vue d’ensemble du projet

• L’objectif d’oxdraw est de faciliter la création et la maintenance de diagrammes de haute qualité grâce à une syntaxe déclarative et reproductible
  • Les diagrammes sont écrits en syntaxe Mermaid, et les ajustements visuels s’effectuent dans l’interface web
  • Les modifications effectuées visuellement par l’utilisateur sont répercutées dans le code source, ce qui permet le contrôle de version et l’automatisation
• Les modifications sont consignées sous forme de commentaires dans le fichier Mermaid, garantissant une compatibilité totale avec les autres outils de l’écosystème Mermaid
• Le dépôt se compose d’une CLI basée sur Rust et d’une interface web basée sur React ; la CLI compile les fichiers .mmd en images

Vision du projet

• Le développeur utilisait auparavant Mermaid pour créer des diagrammes d’architecture ou visualiser des bases de code, mais devait passer à Lucidchart ou à d’autres outils en raison des limites en matière d’édition fine
• oxdraw vise à combiner l’automatisation pilotée par le code de Mermaid et la liberté visuelle de Lucidchart
• L’objectif est ainsi de préserver la reproductibilité, la collaboration et le potentiel d’automatisation des diagrammes générés par le code, tout en améliorant leur qualité visuelle

Mode d’emploi

• Installation via Cargo : cargo install oxdraw
• Rendu d’un diagramme : oxdraw --input flow.mmd
• Lancer l’éditeur interactif : oxdraw --input flow.mmd --edit
• La CLI prend un fichier Mermaid en entrée et génère une sortie SVG ou PNG ; l’option --edit lance un éditeur web local

Description des options CLI

• -i, --input : fichier source Mermaid en entrée
• -o, --output : chemin d’enregistrement du rendu
• --png : sortie au format PNG
• --scale : ajuste l’échelle du rendu PNG (valeur par défaut : 10.0)
• --edit : lance l’éditeur visuel
• --serve-host / --serve-port : définit l’adresse et le port du serveur de l’éditeur (par défaut : 127.0.0.1:5151)
• -b, --background-color : définit la couleur d’arrière-plan (SVG uniquement)
• -q, --quiet : supprime les sorties comme le message de fin de rendu

Fonctionnalités du front-end

• Manipulation des nœuds et des arêtes
  • Suppression du nœud ou de l’arête sélectionné(e) (touches Delete/Backspace prises en charge)
  • Définition et réinitialisation individuelles de la couleur du nœud, de la bordure et de la couleur du texte
  • Réglage de la couleur des arêtes, du style de trait (plein/pointillé) et de la direction des flèches
  • Ajout et suppression de points de contrôle (control points) déplaçables sur le tracé des arêtes
• Interactions avec le canevas et l’éditeur
  • Lors du glissement des nœuds, affichage d’une grille d’alignement et de repères d’alignement
  • Déplacement des nœuds avec Shift+flèches
  • Modification du tracé des arêtes en faisant glisser les poignées, ajout/suppression de poignées par double-clic
  • Prise en charge du déplacement par sous-graphe — les nœuds et arêtes d’un groupe se déplacent ensemble
  • Le panneau source reflète le fichier Mermaid en temps réel et fournit l’enregistrement automatique ainsi que des indicateurs d’état (enregistrement en cours/erreur, etc.)
  • La barre d’outils supérieure affiche le chemin du fichier actuel et l’état de l’enregistrement

Stack technique et licence

• Le projet est composé de Rust 55.7%, TypeScript 40.0%, CSS 3.4% et autres 0.9%
• Il est publié sous licence MIT, ce qui permet une utilisation et des modifications libres
• Il compte actuellement 506 stars et 10 forks, signe d’un intérêt actif de la communauté

Évaluation globale

• oxdraw propose une nouvelle approche qui combine l’automatisation de la gestion des diagrammes pilotés par le code et l’intuitivité de l’édition visuelle
• Tout en conservant une compatibilité totale avec l’écosystème Mermaid, il exploite les performances de Rust et l’interface interactive de React
• Il se distingue comme un outil offrant un workflow de diagrammes collaboratif aussi bien pour les développeurs que pour les designers

[GN⁺]

Commentaires sur Hacker News

• C’est vraiment un super projet. Je pense que le choix de s’appuyer sur Mermaid.js est judicieux, car c’est probablement la bibliothèque de diagrammes déclaratifs la plus populaire actuellement
  Pour prendre en charge des types de diagrammes plus complexes, cela vaut aussi le coup de regarder D2 Language. Il offre une approche déclarative bien plus flexible

• De mon côté, j’ai créé un port MacPorts pour l’utiliser
  Si je m’en sers souvent, je compte contribuer au dépôt officiel MacPorts
  En revanche, l’absence de tag Git ou de release GitHub lié aux releases Cargo complique le packaging
  Pour l’instant, je contourne le problème en considérant qu’un commit précis (9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) correspond à la release 0.1.0
  Le port en question est visible ici

• Ce projet est exactement ce que je cherchais. Il y a une fonctionnalité que j’aimerais vraiment voir dans une solution de diagrammes déclaratifs
  Une fonction de popup qui affiche des informations supplémentaires ou des diagrammes imbriqués au survol de la souris

  • Idée intéressante. Je me demande si ce popup serait destiné à un usage personnel ou au partage avec des collègues
    Par exemple, est-ce que tu voudrais pouvoir partager un lien pour qu’on voie directement le diagramme avec ses popups et imbrications,
    ou bien est-ce qu’il suffit de partager uniquement le fichier .mmd pour l’ouvrir en CLI ?
    Le second cas serait rapide à implémenter, mais le premier pourrait nécessiter un self-hosting avec quelque chose comme ngrok ou un déploiement cloud
    On pourrait aussi ajouter une fonction d’export HTML pour que les popups fonctionnent sans CLI

• Félicitations pour la publication du projet. Je trouve impressionnant le fait de définir les relations avec une syntaxe déclarative tout en permettant une personnalisation fine que les mises en page automatiques existantes ne permettent pas
  En revanche, Cargo.toml indique une licence MIT, mais il n’y a pas de fichier de licence dans le dépôt
  Ce serait bien de l’ajouter pour qu’on puisse le vérifier directement sur GitHub

  • Pour favoriser l’adoption de l’outil, je te recommanderais d’envisager un hébergement. Vu la forte dépendance au code côté serveur, un hébergement statique gratuit semble difficile
  • Le fichier de licence a été ajouté. Merci de me l’avoir signalé

• C’est exactement le genre de projet dont on a besoin. J’utilise surtout PlantUML, et dès qu’il y a plus de 5 composants, je passe 20 à 30 % du temps à ajuster la mise en page
  L’approche consistant à utiliser des annotations pour influencer le moteur de layout est intéressante. Pouvoir définir les coordonnées de certains composants comme contraintes fixes et laisser le reste se placer automatiquement serait très utile
  Si les diagrammes entrent dans le versioning en même temps que les changements de code, la revue de code et la gestion de l’architecture deviennent beaucoup plus naturelles

  • Moi aussi j’utilise PlantUML sur GitLab, mais sur GitHub je suis obligé d’utiliser Mermaid, ce qui est pénible
    La qualité de layout de Mermaid est médiocre, et c’est frustrant de voir GitHub ignorer les demandes de prise en charge de PlantUML
    On dirait que l’adoption des “diagrams as code” dépend du format pris en charge par les grandes plateformes
    Plutôt que de créer un nouveau standard, je pense qu’il serait plus réaliste d’améliorer des choses comme le rendu basé sur le poids des éléments
    La discussion est également abordée dans ce fil de la communauté GitHub

• J’aimerais vraiment que PlantUML résolve ce genre de problème

• Ça ressemble à une version améliorée du langage dot de Graphviz
  Il propose des variables et une syntaxe plus propre, mais les concepts de base restent similaires
  Voir la documentation Graphviz

• Mermaid.js a une notion de moteur de layout
  comme @mermaid-js/layout-elk
  Je me demande si tu envisages d’implémenter ton algorithme comme moteur de layout automatique pour Mermaid

• Super projet. Je l’ai consulté sur mobile et le bouton d’ajout de nœud n’apparaît pas
  Une autre fonctionnalité que j’aimerais serait de pouvoir replier les nœuds descendants (collapse downstream nodes). C’est peut-être hors périmètre, mais ce serait appréciable

  • Pour l’instant, il faut modifier directement le texte .mmd. Mais je pense que c’est une bonne suggestion
    La fonction de repli des nœuds descendants irait aussi très bien avec la fonction d’animation demandée par un autre utilisateur