Quarkdown — Markdown Typesetting with Functions via the CLI

Quarkdown is a Markdown superset and typesetting system that compiles .qd source files to HTML, PDF or plaintext from the command line — a "readable LaTeX" with functions, variables and layouts. The actual engine is a JVM library; the quarkdown command is its main interface. By default quarkdown c main.qd produces static HTML in the quarkdown-output folder; --pdf additionally creates a PDF (via Node.js/Puppeteer), and -p -w enables a live preview with auto-reload. This cheat sheet collects installation, project setup, compile options, the permission system (secure by default), the web server, the REPL and the doctor diagnostics.

Installation

brew install quarkdown-labs/quarkdown/quarkdown — Installs Quarkdown on Linux/macOS via Homebrew.

brew install quarkdown-labs/quarkdown/quarkdown

curl … install.sh | sudo bash — Installs Quarkdown via a script into /opt/quarkdown (Linux/macOS); installs Node.js if needed.

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 — Installs Quarkdown on Windows via Scoop.

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

irm … install.ps1 | iex — Installs Quarkdown on Windows via a PowerShell script.

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

Creating a project

quarkdown create [directory] — Launches the interactive project wizard (metadata, document type, starter content). Without a name, the current directory is used.

quarkdown create my-document

Compiling

quarkdown c <file>.qd — Compiles the source to HTML. With multiple files, point at the root file (the one that includes the others).

quarkdown c main.qd

quarkdown c <file>.qd --pdf — Additionally produces a PDF (requires Node.js, npm and Puppeteer).

quarkdown c main.qd --pdf

quarkdown c -o <directory> — Sets the output directory. Default: ./quarkdown-output. Long: --out

quarkdown c main.qd -o build/

quarkdown c --out-name <name> — Sets the name of the output resource. Default: the document name set via .docname.

quarkdown c main.qd --out-name handbook

quarkdown c -r <renderer> — Selects the target renderer: html (default), html-pdf or text (plaintext). Long: --render

quarkdown c main.qd -r text

Live preview & watch

quarkdown c <file>.qd -p — Enables preview: starts the web server if needed and opens the document in the browser. Long: --preview

quarkdown c main.qd -p

quarkdown c <file>.qd -w — Recompiles on every change in the source directory. Long: --watch

quarkdown c main.qd -w

quarkdown c <file>.qd -p -w — Combines preview and watch for a true live preview.

quarkdown c main.qd -p -w

quarkdown c -b <browser> — Selects the browser for the preview: default, none, xdg, chrome, chromium, firefox, edge (or a path). Long: --browser

quarkdown c main.qd -p -b firefox

quarkdown c --server-port <port> — Sets the local web server's port. Default: 8089.

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

PDF export

quarkdown c --pdf --node-path <path> — Sets the path to the Node.js executable. Default: node.

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

quarkdown c --pdf --npm-path <path> — Sets the path to the npm executable. Default: npm.

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

quarkdown c --pdf --pdf-no-sandbox — Disables the Chrome sandbox during PDF export. Use only when needed (e.g. Linux without a headless sandbox).

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

QD_NPM_PREFIX=<path> quarkdown c --pdf — Sets the directory where node_modules (Puppeteer) is looked for. Default with a package-manager install: lib.

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

Permissions (secure by default)

quarkdown c --allow <permission> — Grants a permission. Values: project-read, global-read, network, native-content, process, all. By default project-read and native-content are granted.

quarkdown c main.qd --allow network

quarkdown c --deny <permission> — Revokes a permission (repeatable, combinable with --allow).

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

quarkdown c --allow global-read — Allows reading outside the project folder (e.g. for files included via .read).

quarkdown c main.qd --allow global-read

Further compiler options

quarkdown c --strict — Aborts on errors instead of rendering them as boxes into the document. Indispensable for CI builds.

quarkdown c main.qd --strict

quarkdown c --clean — Empties the output directory before the build. Destructive operation.

quarkdown c main.qd --clean

quarkdown c --pipe — Outputs the result to stdout (instead of a file) and suppresses logs — ideal for piping.

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

quarkdown c --nowrap — Prevents wrapping in the full document structure; for HTML only the inner content of <body>.

quarkdown c main.qd --nowrap

quarkdown c --pretty — Produces indented, readable output code (for debugging; avoid in production).

quarkdown c main.qd --pretty

quarkdown c --timeout <seconds> — Maximum total runtime. Default: 30 s; 0 disables the limit.

quarkdown c main.qd --timeout 120

quarkdown c --forbid-function-overwriting — Raises an error when a function is declared with an already-used name, instead of silently overwriting it.

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

quarkdown c --no-media-storage — Turns off the media storage system.

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

quarkdown c --subdoc-naming <strategy> — Naming strategy for subdocument outputs: file-name (default), collision-proof, document-name.

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

quarkdown c -l <directory> — Directory to load external libraries from. Default: <install>/lib/qd. Long: --libs

quarkdown c main.qd -l ./libs

quarkdown c -Dloglevel=<level> … — Sets the log level (JVM property). At warning or higher, the output content is no longer printed.

quarkdown c main.qd -Dloglevel=warning

Web server

quarkdown start -f <file> — Starts the web server pointing at the given file (mandatory option). Required to preview paged documents.

quarkdown start -f quarkdown-output/

quarkdown start -f <file> -p <port> — Starts the web server on a specific port. Default: 8089.

quarkdown start -f quarkdown-output/ -p 9000

quarkdown start -f <file> -b <browser> — Opens the served page in the given browser.

quarkdown start -f quarkdown-output/ -b chrome

REPL & diagnostics

quarkdown repl — Opens an interactive REPL to experiment with Quarkdown.

quarkdown repl

quarkdown doctor env — Checks the external runtimes (JVM, Node.js, Puppeteer).

quarkdown doctor env

quarkdown doctor get install-dir — Prints the absolute path of the install directory (handy in shell scripts).

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

quarkdown doctor get agent-skill — Prints the path to the bundled AI agent skill (contains SKILL.md).

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

Conclusion

Quarkdown is at its core a local CLI tool: quarkdown create scaffolds a project, quarkdown c compiles it, -p -w gives you a live preview, and --pdf produces the print-ready artifact. For CI builds, --strict belongs in the mix so errors abort the build hard instead of slipping through silently as boxes. The permission system (--allow/--deny) makes compiling third-party documents safe, and the doctor helps locate environment and paths. Editor comfort comes from the official VS Code extension and the language server — both drive the same CLI under the hood.