Quarkdown: Aus Daten werden Tabellen und Diagramme

Eine Tabelle von Hand in Markdown zu pflegen ist Fleißarbeit; sobald sich die Daten ändern, fängst du von vorn an. Diagramme gehen in reinem Markdown gar nicht — du exportierst Bilder aus einem anderen Werkzeug und hoffst, dass sie aktuell bleiben. Quarkdown dreht das um: Daten sind die Quelle, Tabellen und Diagramme das automatisch generierte Ergebnis. Nach dem Layout aus Teil 4 wird es jetzt datengetrieben.

Tabellen generieren

Tabellen musst du nicht zwingend Zelle für Zelle tippen. .table kombiniert mehrere Tabellen spaltenweise — in Verbindung mit einer Schleife entsteht so eine Tabelle programmatisch:

.table
    .repeat {3}
        n:
        | Spalte .n |
        |-----------|
        | Zelle .n:1 |
        | Zelle .n:2 |

Der Gegenpart ist .tablebyrows: optionale Header plus eine Liste von Zeilen. Das ist ideal, wenn deine Daten ohnehin als Liste vorliegen:

.var {headers}
   - Name
   - Alter
   - Stadt

.tablebyrows {.headers}
    - - John
      - 25
      - NY
    - - Lisa
      - 32
      - LA

CSV direkt einlesen

Richtig praktisch wird es mit .csv {pfad}: Quarkdown lädt eine CSV-Datei und macht daraus eine Tabelle — die erste Zeile ist immer der Header.

.csv {assets/people.csv} caption:{Personendaten.}

Mit mode:{markdown} interpretiert Quarkdown den Zellinhalt als Inline-Quarkdown — dann sind Formatierung und Funktionsaufrufe in den Zellen erlaubt:

Name,  Lieblingsgetränk, Alter
Alice, Kaffee,           .subtract {2026} {1995}
Bob,   *Pepsi*,          .subtract {2026} {2001}

So rechnet die Tabelle ihr Alter beim Kompilieren selbst aus. Geladene CSV-Tabellen lassen sich danach weiterverarbeiten — etwa einzelne Spalten extrahieren (gleich beim Charting nützlich).

Dateien einlesen

.csv ist nur ein Spezialfall des allgemeineren Prinzips: Quarkdown kann Dateien lesen. .read {pfad} liefert den Textinhalt, optional auf einen Zeilenbereich beschränkt (lines:{3..8}, auch offene Bereiche wie ..8 oder 3..). Das glänzt in Kombination mit anderen Funktionen — etwa einen Code-Schnipsel aus der echten Quelldatei in einen Code-Block laden, statt ihn zu kopieren:

.code
    .read {assets/point.ts}

So bleibt dein Dokument synchron mit dem Code, den es zeigt — ein unterschätzter Vorteil für technische Doku.

XY-Charts

Für 2D-Linien- und Balkendiagramme gibt es .xychart (intern auf Mermaid aufsetzend). Die Y-Werte kommen aus dem Body — als statische Liste, aus einer Schleife oder direkt aus einer CSV-Spalte:

.xychart bars:{yes} x:{Monate} y:{Umsatz} yrange:{100..}
    - 250
    - 500
    - 350
    - 450

Der Clou ist die nahtlose Verbindung zu Skripting und Daten. Eine berechnete Kurve entsteht direkt aus einer Schleife mit Mathe-Funktionen …

.xychart
    .repeat {100}
        .1::pow {2}::divide {100}

… und ein Chart aus echten Geschäftsdaten zieht seine Werte aus den Spalten einer CSV:

.xychart
    .tablecolumn {2}
        .csv {assets/sales.csv}

Mit caption wird das Diagramm zusätzlich als Abbildung nummeriert — dazu mehr im Teil über wissenschaftliches Schreiben.

Mermaid-Diagramme

Für alles Übrige — Flowcharts, Sequenz-, Klassen- und Tortendiagramme — bringt .mermaid volle Mermaid-Interoperabilität mit:

.mermaid
    flowchart TD
        A([Start]) --> B[Login]
        B --> C{Korrekt?}
        C -- Ja --> D[Dashboard]
        C -- Nein --> E[Fehlermeldung]

Auch hier gilt Quarkdowns Grundprinzip: Im Mermaid-Code sind Funktionsaufrufe erlaubt. Du kannst Variablen einsetzen, Werte berechnen oder den Diagrammcode per .read {chart.mmd} aus einer Datei laden. Mit caption wird auch das Mermaid-Diagramm als Abbildung nummeriert.

FAQ

Muss ich Mermaid können, um Diagramme zu nutzen?

Für .xychart nicht — das ist reines Quarkdown mit Parametern und einer Werteliste. Für freie Diagrammtypen (Flowchart, Sequenz, Klasse) brauchst du Mermaid-Syntax; die ist aber gut dokumentiert und du kannst klein anfangen.

Woher kommen die Daten für ein Chart?

Aus vier Quellen, die sich frei mischen lassen: einer statischen Liste, einer Schleife (rechnerisch erzeugt), den Spalten einer CSV-Tabelle oder einer Variablen. Genau diese Verzahnung von Daten und Skripting ist Quarkdowns Stärke gegenüber reinen Markup-Sprachen.

Bleiben CSV-Tabellen mit der Quelldatei synchron?

Ja. .csv liest die Datei beim Kompilieren neu ein — änderst du die CSV, ändert sich die Tabelle beim nächsten Build automatisch. Dasselbe gilt für .read-geladene Code-Schnipsel.

Weiterlesen

Die Layout-Grundlagen dazu stehen in Teil 4: Stacks, Container, Boxen & Grids. Als Nächstes geht es ums wissenschaftliche Schreiben: TeX-Formeln, Bibliografie, Cross-References, Fußnoten und die Paper-Bibliothek. Die vollständige Referenz zu Tabellen und Diagrammen findest du in der offiziellen Wiki.