JPKCom DB

Quarkdown — Markdown-Textsatz mit Funktionen über die CLI

Die Quarkdown-CLI: Projekte anlegen, .qd-Quellen zu HTML/PDF/Plaintext kompilieren, Live-Preview, Webserver, Berechtigungen, REPL und Diagnose.

Quarkdown ist ein Markdown-Obermengen- und Textsatz-System, das .qd-Quelldateien über die Kommandozeile zu HTML, PDF oder Plaintext kompiliert — ein „lesbares LaTeX" mit Funktionen, Variablen und Layouts. Die eigentliche Engine ist eine JVM-Bibliothek; der Befehl quarkdown ist ihre Hauptschnittstelle. Standardmäßig erzeugt quarkdown c main.qd statisches HTML im Ordner quarkdown-output; mit --pdf entsteht zusätzlich ein PDF (über Node.js/Puppeteer), und -p -w schaltet eine Live-Vorschau mit Auto-Reload frei. Dieser Spickzettel bündelt Installation, Projekt-Setup, Kompilier-Optionen, das Berechtigungssystem (secure by default), Webserver, REPL und die Doctor-Diagnose.

Installation

brew install quarkdown-labs/quarkdown/quarkdown — Installiert Quarkdown unter Linux/macOS via Homebrew.

brew install quarkdown-labs/quarkdown/quarkdown

curl … install.sh | sudo bash — Installiert Quarkdown per Skript nach /opt/quarkdown (Linux/macOS); installiert bei Bedarf Node.js mit.

curl -fsSL https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.sh | sudo env "PATH=$PATH" bash

scoop bucket add … ; scoop install quarkdown — Installiert Quarkdown unter Windows via Scoop.

scoop bucket add quarkdown https://github.com/quarkdown-labs/scoop-quarkdown; scoop install quarkdown

irm … install.ps1 | iex — Installiert Quarkdown unter Windows per PowerShell-Skript.

irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iex

Projekt anlegen

quarkdown create [verzeichnis] — Startet den interaktiven Projekt-Assistenten (Metadaten, Dokumenttyp, Startinhalt). Ohne Namen wird das aktuelle Verzeichnis genutzt.

quarkdown create mein-dokument

Kompilieren

quarkdown c <datei>.qd — Kompiliert die Quelle zu HTML. Bei mehreren Dateien auf die Wurzeldatei zeigen (die die anderen einbindet).

quarkdown c main.qd

quarkdown c <datei>.qd --pdf — Erzeugt zusätzlich ein PDF (benötigt Node.js, npm und Puppeteer).

quarkdown c main.qd --pdf

quarkdown c -o <verzeichnis> — Setzt das Ausgabeverzeichnis. Standard: ./quarkdown-output. Lang: --out

quarkdown c main.qd -o build/

quarkdown c --out-name <name> — Legt den Namen der Ausgabe-Ressource fest. Standard: der via .docname gesetzte Dokumentname.

quarkdown c main.qd --out-name handbuch

quarkdown c -r <renderer> — Wählt den Ziel-Renderer: html (Standard), html-pdf oder text (Plaintext). Lang: --render

quarkdown c main.qd -r text

Live-Preview & Watch

quarkdown c <datei>.qd -p — Aktiviert die Vorschau: startet bei Bedarf den Webserver und öffnet das Dokument im Browser. Lang: --preview

quarkdown c main.qd -p

quarkdown c <datei>.qd -w — Kompiliert bei jeder Änderung im Quellverzeichnis neu. Lang: --watch

quarkdown c main.qd -w

quarkdown c <datei>.qd -p -w — Kombiniert Preview und Watch zur echten Live-Vorschau.

quarkdown c main.qd -p -w

quarkdown c -b <browser> — Wählt den Browser für die Vorschau: default, none, xdg, chrome, chromium, firefox, edge (oder ein Pfad). Lang: --browser

quarkdown c main.qd -p -b firefox

quarkdown c --server-port <port> — Setzt den Port des lokalen Webservers. Standard: 8089.

quarkdown c main.qd -p --server-port 9000

PDF-Export

quarkdown c --pdf --node-path <pfad> — Setzt den Pfad zur Node.js-Executable. Standard: node.

quarkdown c main.qd --pdf --node-path /usr/local/bin/node

quarkdown c --pdf --npm-path <pfad> — Setzt den Pfad zur npm-Executable. Standard: npm.

quarkdown c main.qd --pdf --npm-path /usr/local/bin/npm

quarkdown c --pdf --pdf-no-sandbox — Deaktiviert die Chrome-Sandbox beim PDF-Export. Nur nutzen, wenn nötig (z. B. Linux ohne Headless-Sandbox).

quarkdown c main.qd --pdf --pdf-no-sandbox

QD_NPM_PREFIX=<pfad> quarkdown c --pdf — Setzt das Verzeichnis, in dem node_modules (Puppeteer) gesucht wird. Standard bei Paketmanager-Installation: lib.

QD_NPM_PREFIX=/opt/quarkdown/lib quarkdown c main.qd --pdf

Berechtigungen (secure by default)

quarkdown c --allow <recht> — Gewährt eine Berechtigung. Werte: project-read, global-read, network, native-content, process, all. Standardmäßig sind project-read und native-content aktiv.

quarkdown c main.qd --allow network

quarkdown c --deny <recht> — Entzieht eine Berechtigung (wiederholbar, kombinierbar mit --allow).

quarkdown c main.qd --allow all --deny network

quarkdown c --allow global-read — Erlaubt das Lesen außerhalb des Projektordners (etwa für eingebundene Dateien per .read).

quarkdown c main.qd --allow global-read

Weitere Compiler-Optionen

quarkdown c --strict — Bricht bei Fehlern ab, statt sie als Boxen ins Dokument zu rendern. Für CI-Builds unverzichtbar.

quarkdown c main.qd --strict

quarkdown c --clean — Leert das Ausgabeverzeichnis vor dem Build. Destruktive Operation.

quarkdown c main.qd --clean

quarkdown c --pipe — Gibt das Ergebnis nach stdout aus (statt in eine Datei) und unterdrückt Logs — ideal zum Weiterleiten.

quarkdown c main.qd --pipe | tidy -indent

quarkdown c --nowrap — Verhindert das Einbetten in die volle Dokumentstruktur; bei HTML nur der Inhalt des <body>.

quarkdown c main.qd --nowrap

quarkdown c --pretty — Erzeugt eingerückten, lesbaren Ausgabecode (zum Debuggen; in Produktion meiden).

quarkdown c main.qd --pretty

quarkdown c --timeout <sekunden> — Maximale Gesamtlaufzeit. Standard: 30 s; 0 deaktiviert das Limit.

quarkdown c main.qd --timeout 120

quarkdown c --forbid-function-overwriting — Wirft einen Fehler, wenn eine Funktion mit bereits vergebenem Namen deklariert wird, statt sie still zu überschreiben.

quarkdown c main.qd --forbid-function-overwriting

quarkdown c --no-media-storage — Schaltet das Media-Storage-System ab.

quarkdown c main.qd --no-media-storage

quarkdown c --subdoc-naming <strategie> — Benennungsstrategie für Subdokument-Ausgaben: file-name (Standard), collision-proof, document-name.

quarkdown c main.qd --subdoc-naming collision-proof

quarkdown c -l <verzeichnis> — Verzeichnis, aus dem externe Bibliotheken geladen werden. Standard: <install>/lib/qd. Lang: --libs

quarkdown c main.qd -l ./libs

quarkdown c -Dloglevel=<level> … — Setzt den Log-Level (JVM-Property). Ab warning wird der Ausgabeinhalt nicht mehr ausgegeben.

quarkdown c main.qd -Dloglevel=warning

Webserver

quarkdown start -f <datei> — Startet den Webserver, der auf die angegebene Datei zeigt (Pflichtoption). Nötig für die Vorschau von paged-Dokumenten.

quarkdown start -f quarkdown-output/

quarkdown start -f <datei> -p <port> — Startet den Webserver auf einem bestimmten Port. Standard: 8089.

quarkdown start -f quarkdown-output/ -p 9000

quarkdown start -f <datei> -b <browser> — Öffnet die ausgelieferte Seite im angegebenen Browser.

quarkdown start -f quarkdown-output/ -b chrome

REPL & Diagnose

quarkdown repl — Öffnet einen interaktiven REPL zum Ausprobieren von Quarkdown.

quarkdown repl

quarkdown doctor env — Prüft die externen Runtimes (JVM, Node.js, Puppeteer).

quarkdown doctor env

quarkdown doctor get install-dir — Gibt den absoluten Pfad des Installationsverzeichnisses aus (praktisch in Shell-Skripten).

INSTALL="$(quarkdown doctor get install-dir)"

quarkdown doctor get agent-skill — Gibt den Pfad zum mitgelieferten KI-Agent-Skill aus (enthält SKILL.md).

ln -s "$(quarkdown doctor get agent-skill)" ~/.claude/skills/quarkdown

Fazit

Quarkdown ist im Kern ein lokales CLI-Werkzeug: quarkdown create legt ein Projekt an, quarkdown c kompiliert es, -p -w gibt dir eine Live-Vorschau, und --pdf erzeugt das druckfertige Artefakt. Für CI-Builds gehört --strict dazu, damit Fehler den Build hart abbrechen statt still als Boxen durchzurutschen. Das Berechtigungssystem (--allow/--deny) macht das Kompilieren fremder Dokumente sicher, und der doctor hilft, Umgebung und Pfade zu finden. Editor-Komfort liefern die offizielle VS-Code-Extension und der Language Server — beide fahren unter der Haube dieselbe CLI.