Quarkdown in der Praxis: CLI, PDF-Export & Deployment

Sieben Teile lang ging es um Inhalt. Jetzt geht es ums Werkzeug: Wie kommst du vom .qd-Quelltext zum fertigen Artefakt — und ins Web? Die Präsentation aus Teil 7 war das letzte Format; dieser Teil ist der praktische Unterbau, den du für jedes Format brauchst.

Ein lokales CLI-Werkzeug

Vorweg zur Einordnung, weil es das ganze Kapitel prägt: Quarkdown läuft größtenteils über die Kommandozeile. Es ist kein Online-Dienst und kein serverseitiger Editor, sondern ein lokal installiertes Werkzeug. Die eigentliche Engine ist eine JVM-Bibliothek (in Kotlin geschrieben); die CLI quarkdown-cli ist die Hauptschnittstelle darauf und stößt den kompletten Pipeline-Prozess an. Neben dem Kompilieren (quarkdown c) gibt es den Projekt-Assistenten (quarkdown create), den Webserver (quarkdown start), einen interaktiven REPL (quarkdown repl) und die Diagnose (quarkdown doctor).

Du musst dafür nicht im Terminal leben: Eine offizielle VS-Code-Extension und ein Language Server (quarkdown-lsp) bieten Preview-Button, Syntax-Hilfe und mehr — sie kapseln die CLI, fahren unter der Haube aber denselben Compiler. In CI/CD ist es schlicht derselbe CLI-Aufruf in einem Workflow. Alles in diesem Teil dreht sich also um genau dieses eine Werkzeug.

Kompilieren

Das Herzstück ist quarkdown c. Bei mehreren Quelldateien zeigst du auf die Wurzeldatei (die die anderen einbindet):

quarkdown c main.qd

Die wichtigsten Optionen:

-o <dir> / --out — Ausgabeverzeichnis (Default ./quarkdown-output), --out-name für den Dateinamen.
-r <renderer> — Ziel: html (Default), html-pdf oder text (Plaintext).
--strict — bricht bei Fehlern ab, statt sie als Boxen ins Dokument zu rendern. Für Builds in CI unverzichtbar.
--clean — leert das Ausgabeverzeichnis vorher (destruktiv).
--pipe — schreibt nach stdout statt in eine Datei, ideal zum Weiterleiten an andere Befehle.
--timeout <s> — Maximaldauer (Default 30 s, 0 deaktiviert).

Live-Preview

Für die Arbeit am Text kombinierst du -p (Preview, öffnet den Browser und lädt nach) mit -w (Watch, kompiliert bei jeder Änderung neu):

quarkdown c main.qd -p -w

Den Browser wählst du per -b (chrome, firefox, edge, none, ein Pfad …), den Port per --server-port. Wichtig zu wissen: Für paged-Dokumente ist ein laufender Webserver Pflicht (eine paged.js-Anforderung) — -p startet ihn automatisch, alternativ geht quarkdown start -f <datei>.

PDF-Export

--pdf erzeugt eine PDF-Datei, die pixelgenau dem entspricht, was Chrome aus dem HTML rendern würde — alle Dokumenttypen und Features inklusive:

quarkdown c main.qd --pdf

Unter der Haube läuft das über Node.js, npm und Puppeteer; Paketmanager und Install-Skripte richten diese Abhängigkeiten gleich mit ein. Auf manchen Linux-Distributionen ohne Headless-Sandbox hilft --pdf-no-sandbox (mit Bedacht einsetzen). Deshalb ist der PDF-Export etwas langsamer als die reine HTML-Kompilierung — er startet einen echten Browser im Hintergrund.

Secure by default: das Berechtigungssystem

Ein Detail, das Quarkdown von vielen Skripting-fähigen Werkzeugen abhebt: Es ist secure by default. Weil .qd-Dokumente Code ausführen können, läuft die Kompilierung in einer restriktiven Sandbox. Standardmäßig sind nur project-read (Lesen im Projektordner) und native-content erlaubt. Alles Weitere musst du explizit freigeben:

quarkdown c main.qd --allow network --allow global-read

Die Berechtigungen heißen project-read, global-read, network, native-content, process und all. Wer fremde .qd-Dateien kompiliert, läuft so nicht Gefahr, dass sie unbemerkt das Netz oder das Dateisystem anfassen — ein durchdachter Sicherheitsansatz.

Diagnose mit dem Doctor

quarkdown doctor berichtet über die Installation. doctor env prüft die externen Runtimes (JVM, Node.js, Puppeteer), doctor get install-dir liefert den Installationspfad (praktisch in Shell-Skripten), und doctor get agent-skill zeigt den Pfad zum mitgelieferten KI-Agent-Skill — dazu mehr im nächsten Teil.

Deployment

Weil der HTML-Build statisch ist, kannst du das Ausgabeverzeichnis auf jeden beliebigen Webspace, in ein CDN oder auf GitHub Pages legen — kein Server-Code nötig. Statische Zusatzdateien (etwa robots.txt oder CNAME) legst du in einen public/-Ordner neben der Hauptdatei; Quarkdown kopiert ihn unverändert ins Output. Für die Automatisierung gibt es eine fertige GitHub-Action — ein CD-Workflow steht laut Projekt in unter drei Minuten. Genauso lässt sich der Build in einen Apache-Unterordner hochladen; das Prinzip „ein Ordner statisches HTML" bleibt dasselbe.

FAQ

Wohin schreibt Quarkdown die Ausgabe?

Standardmäßig nach ./quarkdown-output. Über -o setzt du ein eigenes Verzeichnis — sinnvoll, um Build-Artefakte aus dem Quellordner herauszuhalten. --clean räumt vorher auf, ist aber destruktiv.

Brauche ich für reines HTML auch Node.js?

Nein. Node.js, npm und Puppeteer braucht nur der PDF-Export. Die HTML-Kompilierung läuft allein über die JVM. Wer nie PDFs erzeugt, kann diese Abhängigkeiten ignorieren.

Wie baue ich Quarkdown in CI?

Mit der setup-quarkdown-Action, dann quarkdown c main.qd --strict (damit der Build bei Fehlern rot wird) und einem Deploy-Schritt, der das Ausgabeverzeichnis veröffentlicht. --strict ist hier entscheidend, sonst rendern Fehler still als Boxen ins Dokument.

Weiterlesen

Die letzte inhaltliche Station war Teil 7: Präsentationen. Als Nächstes kommt der Teil, der diese Reihe überhaupt in diesen Blog gebracht hat: Quarkdown & KI — das mitgelieferte Agent-Skill und warum Markdown-natives Arbeiten zum Konzept dieser Plattform passt. Die vollständige Optionsliste findest du in der offiziellen Wiki.