oxdraw - Codebasiertes Diagramm-Tool

 (github.com/RohanAdwankar)
25 Punkte von GN⁺ 2025-10-27 | 1 Kommentare | Auf WhatsApp teilen
  • oxdraw ist ein in Rust geschriebenes „Diagram as Code“-Tool, das dafür entwickelt wurde, codebasierte Diagramme visuell zu bearbeiten und in reproduzierbarer Form zu erhalten
  • Diagramme werden in Mermaid-Syntax geschrieben und können über eine Weboberfläche hinsichtlich Knotenpositionen, Farben, Verbindungen usw. per Drag-and-drop angepasst werden
  • Visuelle Änderungen werden als Kommentare in der Mermaid-Datei gespeichert und bewahren so die Kompatibilität mit anderen Mermaid-Tools
  • Es besteht aus einer CLI und einem React-basierten Web-Editor und unterstützt sowohl Rendering über die Kommandozeile als auch einen Echtzeit-Bearbeitungsmodus
  • Durch die Kombination aus Produktivität codegenerierter Diagramme und der Freiheit visueller Bearbeitung gilt es als Alternative zu GUI-Tools wie Lucidchart

Projektüberblick

  • Ziel von oxdraw ist es, über eine deklarative und reproduzierbare Syntax hochwertige Diagramme einfach zu erstellen und zu pflegen
    • Diagramme werden in Mermaid-Syntax geschrieben, visuelle Anpassungen erfolgen in der Weboberfläche
    • Visuelle Änderungen durch den Nutzer werden in den Quellcode zurückgeschrieben, wodurch Versionsverwaltung und Automatisierung möglich werden
  • Änderungen werden als Kommentare (comment) in der Mermaid-Datei festgehalten und bleiben dadurch vollständig kompatibel mit anderen Tools im Mermaid-Ökosystem
  • Das Repository besteht aus einer Rust-basierten CLI und einer React-basierten Weboberfläche; die CLI kompiliert .mmd-Dateien zu Bildern

Projektvision

  • Der Entwickler hatte zuvor mit Mermaid Architekturdiagramme und Codebase-Visualisierungen erstellt, musste wegen begrenzter Feinbearbeitungsmöglichkeiten jedoch auf Lucidchart und ähnliche Tools wechseln
  • oxdraw zielt darauf ab, die codebasierte Automatisierung von Mermaid mit der visuellen Freiheit von Lucidchart zu verbinden
  • Damit soll die Reproduzierbarkeit, Kollaborationsfähigkeit und Automatisierbarkeit codegenerierter Diagramme erhalten bleiben und zugleich die visuelle Qualität steigen

Verwendung

  • Installation über Cargo möglich: cargo install oxdraw
  • Diagramm rendern: oxdraw --input flow.mmd
  • Interaktiven Editor starten: oxdraw --input flow.mmd --edit
  • Die CLI nimmt Mermaid-Dateien als Eingabe und erzeugt SVG- oder PNG-Ausgaben; mit der Option --edit wird ein lokaler Web-Editor gestartet

Erklärung der CLI-Flags

  • -i, --input : Eingabe der Mermaid-Quelldatei
  • -o, --output : Speicherpfad für das Rendering-Ergebnis festlegen
  • --png: Ausgabe im PNG-Format
  • --scale : Skalierung für PNG-Rendering anpassen (Standardwert 10.0)
  • --edit: Visuellen Editor starten
  • --serve-host / --serve-port : Adresse und Port des Editor-Servers festlegen (Standard 127.0.0.1:5151)
  • -b, --background-color : Hintergrundfarbe festlegen (nur SVG)
  • -q, --quiet: Ausgaben wie die Meldung nach abgeschlossenem Rendering unterdrücken

Frontend-Funktionen

  • Manipulation von Knoten und Kanten
    • Ausgewählte Knoten oder Kanten löschen (Delete-/Backspace-Taste unterstützt)
    • Knotenfarbe, Rahmen und Textfarbe individuell festlegen und zurücksetzen
    • Kantenfarbe, Linienstil (durchgezogen/gestrichelt) und Pfeilrichtung festlegen
    • Ziehbare Kontrollpunkte (control points) auf Kantenpfaden hinzufügen und entfernen
  • Interaktion mit Canvas und Editor
    • Beim Ziehen von Knoten werden Raster-Snapping und Ausrichtungshilfen angezeigt
    • Knoten mit Shift+Pfeiltasten verschieben
    • Kantenpfade durch Ziehen der Handles bearbeiten, per Doppelklick Handles hinzufügen/entfernen
    • Verschieben auf Subgraph-Ebene unterstützt — Knoten und Kanten innerhalb einer Gruppe werden gemeinsam verschoben
    • Das Quelltext-Panel aktualisiert die Mermaid-Datei in Echtzeit und bietet Auto-Save sowie Statusanzeigen (Speichern/Fehler usw.)
    • In der oberen Toolbar werden der aktuelle Dateipfad und der Speicherstatus angezeigt

Technischer Aufbau und Lizenz

  • Besteht aus Rust 55,7 %, TypeScript 40,0 %, CSS 3,4 % und sonstigen Anteilen von 0,9 %
  • Unter der MIT-Lizenz veröffentlicht und frei nutzbar sowie modifizierbar
  • Derzeit mit 506 Stars und 10 Forks und auf reges Interesse der Community stoßend

Gesamtbewertung

  • oxdraw ist ein neuer Ansatz, der die Automatisierung codebasierter Diagrammverwaltung mit der Intuitivität visueller Bearbeitung verbindet
  • Es bewahrt vollständige Kompatibilität mit dem Mermaid-Ökosystem und nutzt zugleich die Performance von Rust sowie die interaktive UI von React
  • Das Tool wird als Lösung wahrgenommen, die einen kollaborativen Diagramm-Workflow für Entwickler und Designer gleichermaßen ermöglicht

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2025-10-27
Hacker-News-Kommentare

  • Wirklich ein großartiges Projekt. Die Entscheidung für Mermaid.js ist aus meiner Sicht naheliegend, weil es aktuell die populärste deklarative Diagramm-Bibliothek ist.
    Wenn du komplexere Diagrammtypen unterstützen willst, lohnt sich auch ein Blick auf D2 Language. Das bietet einen deutlich flexibleren deklarativen Ansatz.

  • Ich habe mir persönlich bereits einen MacPorts-Port dafür gebaut und nutze ihn.
    Wenn ich es häufiger verwende, will ich ihn vermutlich zum offiziellen MacPorts-Repository beitragen.
    Etwas unpraktisch fürs Packaging ist allerdings, dass es keine Git-Tags oder GitHub-Releases gibt, die mit den Cargo-Releases verknüpft sind.
    Im Moment behelfe ich mir damit, einen bestimmten Commit (9ccd9bf53f9a309ccda42b5c17e9c1056493fb90) vorläufig als Release 0.1.0 zu behandeln.
    Den zugehörigen Port kann man hier sehen.

  • Dieses Projekt ist wirklich genau das, wonach ich gesucht habe. Es gibt eine Funktion, die ich in einer deklarativen Diagramm-Lösung unbedingt sehen möchte.
    Nämlich eine Popup-Funktion, die bei Mouseover zusätzliche Informationen oder verschachtelte Diagramme anzeigt.

    • Spannende Idee. Mich würde interessieren, ob dieses Popup eher für den Eigengebrauch gedacht ist oder zum Teilen mit Teammitgliedern.
      Geht es dir zum Beispiel darum, einen Link zu teilen, damit man direkt ein Diagramm mit Popups und Verschachtelungen ansehen kann,
      oder reicht es, nur eine .mmd-Datei zu teilen, die dann per CLI geöffnet wird?
      Letzteres ließe sich schnell umsetzen, aber Ersteres könnte Self-Hosting mit etwas wie ngrok oder ein Cloud-Deployment erfordern.
      Alternativ könnte man auch eine HTML-Datei exportieren, sodass die Popups auch ohne CLI funktionieren.

  • Glückwunsch zur Veröffentlichung des Projekts. Beeindruckend finde ich, dass du Beziehungen mit einer deklarativen Syntax definierst und gleichzeitig feingranulare Anpassungen ermöglichst, die bestehende Auto-Layout-Lösungen nicht leisten.
    In Cargo.toml ist allerdings zwar eine MIT-Lizenz angegeben, im Repository fehlt aber eine Lizenzdatei.
    Es wäre gut, die noch hinzuzufügen, damit man das direkt auf GitHub sehen kann.

    • Um die Adoption des Tools zu erhöhen, würde ich empfehlen, über Hosting nachzudenken. Wegen der starken Abhängigkeit von serverseitigem Code dürfte kostenloses statisches Hosting schwierig sein.
    • Die Lizenzdatei ist jetzt hinzugefügt. Danke für den Hinweis.

  • Das ist wirklich ein Projekt, das gebraucht wird. Ich nutze meistens PlantUML, aber sobald es mehr als fünf Komponenten gibt, verbringe ich 20–30 % der Zeit mit Layout-Anpassungen.
    Der Ansatz, Kommentare zu verwenden und sie in der Layout-Engine zu berücksichtigen, ist interessant. Es wäre vermutlich nützlich, die Koordinaten bestimmter Komponenten als feste Constraints zu setzen und den Rest automatisch anzuordnen.
    Wenn Diagramme zusammen mit Codeänderungen versioniert werden, werden Code-Reviews und Architekturpflege sehr viel natürlicher.

    • Ich verwende auf GitLab auch PlantUML, muss auf GitHub aber Mermaid verwenden, was lästig ist.
      Die Layout-Qualität von Mermaid ist schwach, und es ist schade, dass GitHub Anfragen nach PlantUML-Support ignoriert.
      Es wirkt so, als würde die Adoption von „diagrams as code“ von den Formaten bestimmt, die die großen Plattformen unterstützen.
      Statt einen neuen Standard zu schaffen, halte ich Verbesserungen wie gewichtungsbasiertes Rendering von Elementen für realistischer.
      Die Diskussion dazu wird auch in einer GitHub-Community-Diskussion geführt.

  • Ich hoffe sehr, dass PlantUML solche Probleme lösen wird.

  • Das wirkt wie eine erweiterte Version der dot-Sprache von Graphviz.
    Es bietet Variablen und eine sauberere Syntax, aber die Grundidee ist ähnlich.
    Siehe die Graphviz-Dokumentation.

  • Mermaid.js hat bereits ein Konzept für Layout-Engines.
    Zum Beispiel @mermaid-js/layout-elk.
    Ich frage mich, ob du darüber nachgedacht hast, deinen Algorithmus als Auto-Layout-Engine für Mermaid umzusetzen.

  • Tolles Projekt. Ich habe es auf dem Handy angesehen, aber der Button zum Hinzufügen von Knoten war nicht sichtbar.
    Eine weitere Funktion, die ich mir wünschen würde, wäre das Einklappen nachgelagerter Knoten (collapse downstream nodes). Das liegt vielleicht außerhalb des Scopes, wäre aber schön zu haben.

    • Momentan muss man den .mmd-Text direkt bearbeiten. Aber ich halte das für einen guten Vorschlag.
      Die Funktion zum Einklappen nachgelagerter Knoten würde vermutlich auch gut zu der von anderen Nutzern gewünschten Animationsfunktion passen.