Quarkdown: Tipps & Tricks aus der Praxis

Zum Abschluss der Reihe sammle ich die Kniffe, die in den vorherigen zehn Teilen nur am Rand vorkamen — die kleinen Dinge, die den Alltag mit Quarkdown spürbar leichter machen. Nach dem Blick in die Pipeline wird es noch einmal praktisch und kompakt.

Die Leerzeile ist heilig

Der mit Abstand häufigste Stolperstein, deshalb zuerst: Stack-Funktionen wie .row trennen Elemente am Block — und Blöcke entstehen durch Leerzeilen. A, B, C ohne Leerzeilen dazwischen sind ein Absatz und ergeben eine Spalte. Immer eine Leerzeile zwischen die Items setzen. (Mehr dazu in Teil 4.)

Lesbarkeit: Verkettung und Zeilenfortsetzung

Verschachtelte Aufrufe werden mit :: von innen-nach-außen zu links-nach-rechts — .pow {3} {2}::subtract {1}::sum {2} liest sich wie Mathematik. Und wenn ein Aufruf viele Argumente hat, bricht ein Backslash am Zeilenende die Argumentliste sauber um:

.container alignment:{center} \
           background:{red} \
           padding:{1px}

Funktionsaufrufe mitten im Wort

Ein Aufruf direkt an einem Wortzeichen wird normal nicht erkannt. Wickelst du ihn in geschweifte Klammern, darf er überall stehen — die Klammern verschwinden im Output:

H{.text {2} script:{sub}}O

Kompakte Fußnoten

Statt Referenz und Definition zu trennen, kannst du eine Fußnote direkt an Ort und Stelle definieren:

… und vieles mehr[^: Alle Markdown-Features werden unterstützt].

Lebende Code-Blöcke

Die .code-Funktion ist der dynamische Bruder des Triple-Backtick-Blocks: Sie wertet ihren Body als Quarkdown aus. In Kombination mit .read lädst du einen Schnipsel aus der echten Quelldatei — der Block bleibt damit automatisch synchron mit dem Code, den er zeigt:

.code lang:{typescript} focus:{5..8}
    .read {assets/point.ts}

focus:{5..8} hebt einen Zeilenbereich hervor, linenumbers:{no} schaltet die Nummerierung ab. Für Inline-Code mit Funktionsauswertung gibt es analog .codespan.

Rechnende CSV-Tabellen

.csv mit mode:{markdown} interpretiert Zellinhalte als Inline-Quarkdown — so rechnen Tabellen beim Kompilieren selbst und bleiben mit der Datenquelle synchron (siehe Teil 5). Ein unterschätzter Hebel für Reports, die sich mit den Daten aktualisieren.

Text-Symbole geschenkt

Quarkdown ersetzt gängige Symbole automatisch in Fließtext (nicht in Code/Math/URLs): -- wird —, -> wird →, >= wird ≥, != wird ≠, (C) wird ©, (TM) wird ™, und gerade Anführungszeichen werden zu typografischen. Soll ein Zeichen nicht ersetzt werden, stellst du einen Backslash voran: \->.

Kleine Helfer: Collapse und Icons

.collapse {Titel} erzeugt einen aufklappbaren Block — ideal für FAQ-artige Details oder lange Beispiele; open:{yes} startet ihn geöffnet. Und .icon {github} setzt ein pixelgenaues Bootstrap-Icon mitten in den Text.

Dekorative Überschriften

Eine Überschrift mit ! (also ##! statt ##) wird nicht nummeriert und nicht ins Inhaltsverzeichnis aufgenommen — praktisch für Zwischentitel in Layout-Blöcken, die nicht in die Gliederung gehören.

Eigene Mini-Bibliothek

Wiederkehrende Funktionen musst du nicht in jedes Dokument kopieren. Lege sie in eine eigene .qd-Datei und binde sie per .include {name} (ohne Endung) ein — genau wie die eingebaute paper-Bibliothek aus Teil 6. So entsteht aus deinen Bausteinen eine wiederverwendbare Stilbibliothek.

Und immer: `--strict`

Im Normalbetrieb rendert Quarkdown Fehler als Boxen ins Dokument — praktisch beim Schreiben, gefährlich in der Produktion. In jedem automatisierten Build gehört darum --strict dazu, damit ein Fehler den Build hart abbrechen lässt statt still durchzurutschen.

FAQ

Was ist der eine Tipp, den ich mir merken sollte?

Die Leerzeile. Gefühlt neun von zehn „Warum sieht das falsch aus?"-Momenten in Quarkdown gehen darauf zurück, dass zwischen zwei Blöcken die trennende Leerzeile fehlt.

Wie organisiere ich ein größeres Projekt?

Setup und Inhalt trennen (.include {setup.qd}), wiederkehrende Komponenten in eine eigene Bibliotheks-.qd auslagern und für Wissensbasen mit Subdocuments arbeiten. So bleibt auch ein großes Dokument wartbar.

Wo finde ich alle Funktionen?

In der Standardbibliothek — sie listet jede Funktion mit Signatur, Parametern und Rückgabetyp. Für konzeptionelle Erklärungen ist die Wiki die richtige Anlaufstelle.

Die Reihe im Überblick

Damit ist die Reihe komplett. Sie führt vom Einstieg über Skripting, Dokumenttypen & Themes, Layout, Daten & Diagramme, wissenschaftliches Schreiben, Präsentationen, CLI & Deployment und den KI-Teil bis hinter die Kulissen. Die vollständige Referenz bleibt die offizielle Wiki.