D2 (Tool für Text-zu-Diagramm) unterstützt jetzt ASCII-Rendering

 (d2lang.com)
4 Punkte von GN⁺ 2025-08-20 | 1 Kommentare | Auf WhatsApp teilen
  • In D2 Version 0.7.1 wurde eine Funktion hinzugefügt, die Textdiagramme als ASCII rendert
  • Mit einfachen ASCII-Diagrammen in Code-Kommentaren lassen sich Abläufe von Funktionen oder Klassen erklären
  • Standardmäßig werden Unicode-Zeichen verwendet, per Options-Flag kann aber auch Standard-ASCII gewählt werden
  • Die Funktion befindet sich in der Alpha-Phase; einige Styles, Sonderzeichen und bestimmte Formen werden nicht unterstützt
  • In der D2 Playground und der Vim-Erweiterung lässt sich das ASCII-Rendering direkt ausprobieren

Einführung in D2-ASCII-Rendering

Seit dem neuesten Release von D2 (Version 0.7.1) gibt es eine ASCII-Ausgabefunktion für Textdiagramme.
Ausgabedateien mit der Endung .txt werden automatisch mit dem ASCII-Renderer gerendert.
Ein Beispiel ist in der D2-Vim-Erweiterung zu sehen: Öffnet man eine .d2-Datei, lässt sich im Vorschaufenster beim Speichern in Echtzeit verfolgen, wie das ASCII-Diagramm ausgegeben wird.

Einsatz in der Code-Dokumentation

ASCII-Diagramme sind besonders praktisch, wenn sie in Quellcode-Kommentare eingefügt werden.

  • Fügt man neben einer kleinen Funktion oder Klasse ein einfaches Diagramm hinzu, hilft das beim Verständnis des Codes oft intuitiver als eine reine Ablaufbeschreibung
  • In der Vim-Erweiterung kann D2-Code geschrieben und eine Auswahl sofort in ein ASCII-Diagramm umgewandelt werden

Wahl zwischen Unicode und Standard-ASCII

Das standardmäßige ASCII-Rendering nutzt Unicode-Box-Zeichen und liefert dadurch eine ansprechendere Ausgabe.

  • Wenn maximale Portabilität gewünscht ist, kann mit dem Options-Flag --ascii-mode=standard auch mit normalen ASCII-Zeichen gerendert werden

Aktuelle Einschränkungen

Diese ASCII-Rendering-Funktion befindet sich in der Alpha-Phase.

  • Es kann viele Corner Cases, Verbesserungsmöglichkeiten und Bugs geben
  • Auf der Website wird dazu ermutigt, Bug-Reports oder Feedback einzureichen

Wichtige Einschränkungen

  • Keine Style-Unterstützung
    • Animationen, Schriftarten usw. haben in ASCII keine Bedeutung
    • Künftig wird geprüft, ob begrenzte Style-Unterstützung wie Terminal-Farben möglich ist
    • Themes werden ebenfalls nicht unterstützt
    • double-border, multiple usw. stehen auf der Liste für künftige Verbesserungen
  • Uneinheitliche Abstände
    • Beim Umwandeln in ASCII kann die Platzierung von Boxen im Vergleich zu SVG unregelmäßiger werden
  • Nicht renderbare Inhalte
    • Unterstützung für speziellen Text wie Markdown, Latex und Code ist noch nicht implementiert
    • Bilder und Icons, UML-Klassen, SQL-Tabellen usw. können nicht gerendert werden
    • Für solche Elemente soll später entschieden werden, ob sie entfernt oder durch Platzhalter angezeigt werden
  • Einige Formen nicht unterstützt
    • Wolken, Kreise und andere kurvige Formen lassen sich in ASCII nicht gut darstellen
    • Solche Formen werden durch Rechtecke ersetzt; oben links wird ein kleines Icon hinzugefügt, um den Typ zu kennzeichnen

Selbst ausprobieren

Diese Funktion kann direkt in der D2 Playground ausprobiert werden.

  • Den bereitgestellten Codeblock kann man öffnen und das ASCII-Rendering selbst testen

Verwandte Beiträge

1 Kommentare

 
GN⁺ 2025-08-20
Hacker-News-Kommentare

  • Hallo zusammen, ich wollte die neue Funktion vorstellen, die ich heute Morgen hinzugefügt habe. Sie ist noch im Alpha-Stadium, und es gibt bereits ein GitHub-Issue dazu. Wenn ihr den Blogpost überspringen und es direkt ausprobieren wollt, könnt ihr es hier ansehen. Ein etwas größeres Beispiel gibt es auch unter diesem Link

    • Im Playground wurde es mit schwarzer Schrift auf schwarzem Hintergrund gerendert, sodass ich dachte, es funktioniert nicht. Vermutlich liegt es daran, dass ich den Dark Mode aktiviert habe. Andere Renderer funktionieren, aber ASCII ist nicht sichtbar.
    • Bedeutet das im TFA einfach, dass auf ELK herunterskaliert wird? Ich frage mich, ob man ELK explizit aktivieren muss, um diese Funktion zu nutzen, oder ob sie automatisch aktiv wird, wenn man nach .txt ausgibt. Ich nutze für meine D2-Diagramme ohnehin bereits ELK.

  • Ich frage mich, worin im Vergleich zu Mermaid der Mehrwert liegt. Mir gefallen das Design und die Funktionsweise, aber ich würde gerne wissen, ob es einen praktischen Grund gibt, von Mermaid zu wechseln. Außerdem habe ich den Eindruck, dass solchen Tools meist die Möglichkeit fehlt, bei automatisch erzeugten Ergebnissen Position und Größe von Boxen manuell über x/y-Werte anzupassen.

    • Kommt darauf an, welchen Wert man besonders wichtig findet. Für manche reichen die beiden Punkte, die du genannt hast, bereits aus, und für Leute wie uns ist wichtig, dass man beim SVG-Rendering in der CLI keinen Chromium-Browser braucht (siehe diesen Fall). Es zeigt nicht alle Unterschiede, aber es gibt auch eine kurze Vergleichsseite. Und ich will hier zwar kein kostenpflichtiges Produkt bewerben, aber wenn du manuelle Anpassungen brauchst, um Position und Größe festzulegen, bietet die IDE das an.

  • Obwohl die D2-Syntax sehr attraktiv ist, habe ich bisher wegen des Toolings häufiger Mermaid verwendet. Diese Funktion ist jedoch eine große Neuerung, so etwas habe ich bei Mermaid noch nicht gesehen. Sie schafft auch eine gute Verbindung zu asciiflow.com.

  • Die Umwandlung aus ASCII ist gut. Aber wenn man das Diagramm später aktualisieren muss, frage ich mich, wie man wieder an den ursprünglichen D2-Quelltext kommt.

  • D2 hat mir immer besser gefallen als Mermaid, aber meiner Meinung nach macht das folgende Issue das Grid-Layout praktisch unbrauchbar (zugehöriges Issue). Wenn man Pixelwerte direkt selbst anpassen muss, verfehlt so ein Tool seinen Zweck.

    • Danke! Gut, dass du das gemeldet hast. Das wird in 0.7.2 (dem nächsten Release) berücksichtigt.

  • Ich habe schon mehrfach eine Liste browserbasierter Text-zu-Diagramm-Tools gepflegt und geteilt. Was ich kürzlich gelernt habe: Die Online-Version von D2 läuft nicht rein im Browser, sondern ein Backend-Server erzeugt die Diagramme. Ich frage mich, ob D2 vollständig nur im Client (Browser) laufen kann und ob die in diesem Beitrag erwähnte Erweiterung auch offline funktioniert.

    • Inzwischen ja! (seit etwa einer Woche) Wenn du im D2-Playground den Netzwerk-Tab ansiehst, wirst du d2.js sehen, das von einem Wrapper um den Wasm-Port von D2 angetrieben wird. Es ist noch nicht offiziell veröffentlicht, aber die Ankündigung zur Abspaltung kommt bald.
    • ~~Ich wollte fragen, ob ich die Liste sehen könnte~~ Bearbeitung: Schon gefunden! Danke.

  • Ich würde mir ein offizielles Python-Repository wünschen. Ich möchte es in Notebooks verwenden, aber aktuell ist man dabei unangenehm auf Databricks festgelegt.

  • Sieht wirklich großartig aus. Ich habe auch den früheren Beitrag zur C4-Unterstützung gesehen! Ich brauche bald C4-Modellierung und werde es mir dann anschauen.

  • Wirklich eine tolle Funktion. Ich hatte vorher noch nie von D2 gehört, aber mir gefällt sehr, dass man direkt im Terminal Diagramme erstellen und sie auch noch hübsch rendern kann. Ich werde es sehr bald ausprobieren.

    • D2 unterstützt bereits das Live-Aktualisieren von .svg über einen Echtzeit-HTTP-Server. Wenn man Browser und vim nebeneinander offen hat, kann man Aktualisierungen in Echtzeit sehen. Ich habe D2 vor einem Jahr entdeckt und verwende es seitdem für alle Diagramme.
    • Normalerweise nutze ich für ASCII-Diagramme Moondraw, aber wenn man ohnehin schon in einer vim-Umgebung ist, ist dieses Tool viel besser.

  • Die vim-Erweiterung ist wirklich der Hammer.

    • Dass sie in vimscript geschrieben ist, ist allerdings seltsam und etwas schade.