# 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.

Source: https://www.jpkc.com/db/cheatsheets/build-languages/quarkdown/

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.

```bash
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.

```bash
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.

```bash
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.

```powershell
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.

```bash
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).

```bash
quarkdown c main.qd
```

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

```bash
quarkdown c main.qd --pdf
```

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

```bash
quarkdown c main.qd -o build/
```

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

```bash
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

```bash
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

```bash
quarkdown c main.qd -p
```

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

```bash
quarkdown c main.qd -w
```

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

```bash
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

```bash
quarkdown c main.qd -p -b firefox
```

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

```bash
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`.

```bash
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`.

```bash
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).

```bash
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`.

```bash
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.

```bash
quarkdown c main.qd --allow network
```

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

```bash
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`).

```bash
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.

```bash
quarkdown c main.qd --strict
```

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

```bash
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.

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

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

```bash
quarkdown c main.qd --nowrap
```

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

```bash
quarkdown c main.qd --pretty
```

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

```bash
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.

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

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

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

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

```bash
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

```bash
quarkdown c main.qd -l ./libs
```

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

```bash
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.

```bash
quarkdown start -f quarkdown-output/
```

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

```bash
quarkdown start -f quarkdown-output/ -p 9000
```

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

```bash
quarkdown start -f quarkdown-output/ -b chrome
```

## REPL & Diagnose

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

```bash
quarkdown repl
```

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

```bash
quarkdown doctor env
```

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

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

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

```bash
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.

## Weiterführende Links

- [Quarkdown-Wiki: CLI-Optionen](https://quarkdown.com/wiki/cli-options) – vollständige Referenz aller Compiler- und REPL-Optionen (englisch)
- [Quarkdown-Wiki](https://quarkdown.com/wiki) – Einstieg, Quickstart und Sprachreferenz (englisch)
- [Standardbibliothek](https://quarkdown.com/docs/) – alle Funktionen mit Signatur und Rückgabetyp (englisch)