Markdown auf Steroiden: Quarkdown 2.0 ist da

Der Markdown-Dialekt Quarkdown ist in Version 2.0.0 erschienen. Im Mittelpunkt des Updates stehen ein neues Berechtigungssystem, das den Zugriff eines Dokuments während der Kompilierung einschränkt, und eine HTML-Ausgabe, die vollständig offline funktioniert. Hinzu kommen paralleles Rendering, neue HTML-Optionen für Canonical Links und eine sitemap.xml sowie ein public/-Verzeichnis für statische Assets. Mehrere Breaking Changes betreffen außerdem das Standard-Ausgabeverzeichnis, den Namen des Ausgabeverzeichnisses bei --preview und ein umbenanntes Modul der Standardbibliothek.

Quarkdown erweitert die Auszeichnungssprache um eine Turing-vollständige Funktionssprache. Anders als klassisches Markdown erlaubt das Open-Source-Projekt damit Variablen, Funktionen und Kontrollstrukturen direkt im Dokument. Es zielt auf HTML- und PDF-Ausgaben für Bücher, Fachtexte, Wissenssammlungen und Präsentationen. Wer Markdown kennt, kann sich Quarkdown am ehesten als Markdown mit eingebauter Skript- und Layoutschicht vorstellen.

Berechtigungssystem als Sandbox

Die wichtigste Neuerung ist das Berechtigungssystem. Es legt fest, worauf ein Dokument während der Kompilierung zugreifen darf. Versucht der Compiler eine Aktion ohne passende Berechtigung, bricht er mit einem Fehler ab. Freigaben und Verbote setzen Nutzer über --allow und --deny; vorgesehen sind unter anderem project-read, global-read, network, native-content und all. Das Feature wirkt vor allem als Sandbox: Weil Quarkdown-Dokumente dank ihrer Funktionssprache deutlich mehr können als reines Markdown, lässt sich die Ausführung fremder Dokumente damit besser absichern.

Ebenfalls zentral ist die überarbeitete HTML-Ausgabe. Quarkdown liefert Schriften, Code-Highlighting-Themes und optionale Bibliotheken jetzt mit der Installation aus und kopiert sie in die generierten Dokumente, statt sie von CDNs oder Google Fonts nachzuladen. Damit funktioniert die Ausgabe vollständig offline. Laut Release Notes sorgt das zugleich für vorhersagbareres Rendering und schnellere Seitenaufrufe. Lediglich chinesische Schriften bei .doclang {zh} sowie explizit gewählte Google Fonts bleiben remote. Der Preis sind größere Ausgabeverzeichnisse und ein etwas langsamerer Erstlauf; Folgekompilierungen bremsen Prüfsummen-Checks dem Projekt zufolge nicht aus.

Für HTML-Projekte führt Quarkdown außerdem die neue Funktion .htmloptions ein. Mit gesetztem baseurl erzeugt sie Canonical Links im jeder Seite und schreibt eine sitemap.xml mit absoluten URLs für Haupt- und Unterdokumente. Damit rückt Quarkdown näher an typische Static-Site-Generatoren heran, ohne dass Nutzer solche SEO-Metadaten nachträglich ergänzen müssen.

Statische Assets und neue Funktionen

Praktisch für Web-Ausgaben ist auch das neue Verzeichnis public/ im Projektwurzelverzeichnis. Dessen Inhalt – etwa robots.txt, CNAME oder andere statische Dateien – landet unverändert im Wurzelverzeichnis der Ausgabe. Ergänzend versteht Quarkdown beim HTML-Export jetzt das Wurzelpfadsymbol @: Ein Verweis wie @/assets/logo.png zeigt auf die Ausgabewurzel und eignet sich damit für Assets, die mehrere Unterdokumente gemeinsam nutzen. Das Konzept erinnert an die public/-Ordner gängiger Web-Frameworks.

Neu ist zudem die Primitivfunktion .image, die Bilder feiner konfigurierbar macht, einschließlich eines Opt-outs aus dem Media Storage über mediastorage:{no}. Querverweise per .ref rendert Quarkdown jetzt für alle referenzierbaren Typen als Links – also nicht nur für Überschriften, sondern auch für Abbildungen, Tabellen, Code-Blöcke, Gleichungen und benutzerdefinierte nummerierte Blöcke. In längeren technischen Dokumenten wird die Navigation dadurch deutlich konsistenter.

Zu den kleineren, aber nützlichen Komfortfunktionen zählen mehrzeilige Funktionsaufrufe per Backslash am Zeilenende und die neue Funktion .keybinding für Tastenkürzel. Letztere stellt Shortcuts als stilisierte Tastenbeschriftungen dar und berücksichtigt Plattformunterschiede, etwa mit ⌘ statt Ctrl auf macOS. Das ist praktisch für Bereiche wie Dokumentation, Wissenssammlungen und UI-nahe Inhalte.

Mehr Tempo und Bugfixes

Unter der Haube rendert Quarkdown 2.0 Geschwisterelemente jetzt parallel, was große Dokumente beschleunigen soll. Überarbeitet hat das Projekt auch die Ein- und Ausgabe des Media Storage: Dateien kopiert Quarkdown nun per Referenz statt per Inhalt, ergänzt um Prüfsummen, die unnötige Kopien vermeiden.

Bestehende Setups müssen sich auf einige Inkompatibilitäten einstellen. Das Standard-Ausgabeverzeichnis heißt jetzt ./quarkdown-output statt ./output. Bei --preview ohne --out-name vergibt Quarkdown künftig statische Namen nach dem Muster preview--, statt sich an .docname zu orientieren. Hinzu kommt eine Umbenennung in der Standardbibliothek: Das bisherige Modul Injection heißt nun Html; bestehende Verweise auf die Dokumentation des Moduls und seiner Funktionen müssen daher angepasst werden.

Lizenz und Installation

Alle Informationen zu Quarkdown 2.0.0 finden sich in den Release Notes auf GitHub. Das Projekt ist Open Source: Quarkdown und seine Module stehen standardmäßig unter GNU GPLv3; für die Module und Binärpakete von quarkdown-cli und quarkdown-lsp gilt die GNU AGPLv3. Installieren lässt sich die Software per Installationsskript unter Linux, macOS und Windows sowie über Homebrew oder Scoop; alternativ verweist das Projekt auf ein quarkdown.zip aus dem aktuellen Stable-Release oder einen Build via gradlew installDist.

(fo)