# Quarkdown — Markdown Typesetting with Functions via the CLI > The Quarkdown CLI: create projects, compile .qd sources to HTML/PDF/plaintext, live preview, web server, permissions, REPL and diagnostics. Source: https://www.jpkc.com/db/en/cheatsheets/build-languages/quarkdown/ 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. ```bash 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. ```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` — Installs Quarkdown on Windows via Scoop. ```bash 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. ```powershell 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. ```bash quarkdown create my-document ``` ## Compiling `quarkdown c .qd` — Compiles the source to HTML. With multiple files, point at the root file (the one that includes the others). ```bash quarkdown c main.qd ``` `quarkdown c .qd --pdf` — Additionally produces a PDF (requires Node.js, npm and Puppeteer). ```bash quarkdown c main.qd --pdf ``` `quarkdown c -o ` — Sets the output directory. Default: `./quarkdown-output`. Long: --out ```bash quarkdown c main.qd -o build/ ``` `quarkdown c --out-name ` — Sets the name of the output resource. Default: the document name set via `.docname`. ```bash quarkdown c main.qd --out-name handbook ``` `quarkdown c -r ` — Selects the target renderer: `html` (default), `html-pdf` or `text` (plaintext). Long: --render ```bash quarkdown c main.qd -r text ``` ## Live preview & watch `quarkdown c .qd -p` — Enables preview: starts the web server if needed and opens the document in the browser. Long: --preview ```bash quarkdown c main.qd -p ``` `quarkdown c .qd -w` — Recompiles on every change in the source directory. Long: --watch ```bash quarkdown c main.qd -w ``` `quarkdown c .qd -p -w` — Combines preview and watch for a true live preview. ```bash quarkdown c main.qd -p -w ``` `quarkdown c -b ` — Selects the browser for the preview: default, none, xdg, chrome, chromium, firefox, edge (or a path). Long: --browser ```bash quarkdown c main.qd -p -b firefox ``` `quarkdown c --server-port ` — Sets the local web server's port. Default: 8089. ```bash quarkdown c main.qd -p --server-port 9000 ``` ## PDF export `quarkdown c --pdf --node-path ` — Sets the path to the Node.js executable. Default: `node`. ```bash quarkdown c main.qd --pdf --node-path /usr/local/bin/node ``` `quarkdown c --pdf --npm-path ` — Sets the path to the npm executable. Default: `npm`. ```bash 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). ```bash quarkdown c main.qd --pdf --pdf-no-sandbox ``` `QD_NPM_PREFIX= quarkdown c --pdf` — Sets the directory where `node_modules` (Puppeteer) is looked for. Default with a package-manager install: `lib`. ```bash QD_NPM_PREFIX=/opt/quarkdown/lib quarkdown c main.qd --pdf ``` ## Permissions (secure by default) `quarkdown c --allow ` — Grants a permission. Values: project-read, global-read, network, native-content, process, all. By default project-read and native-content are granted. ```bash quarkdown c main.qd --allow network ``` `quarkdown c --deny ` — Revokes a permission (repeatable, combinable with --allow). ```bash 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`). ```bash 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. ```bash quarkdown c main.qd --strict ``` `quarkdown c --clean` — Empties the output directory before the build. Destructive operation. ```bash quarkdown c main.qd --clean ``` `quarkdown c --pipe` — Outputs the result to stdout (instead of a file) and suppresses logs — ideal for piping. ```bash quarkdown c main.qd --pipe | tidy -indent ``` `quarkdown c --nowrap` — Prevents wrapping in the full document structure; for HTML only the inner content of ``. ```bash quarkdown c main.qd --nowrap ``` `quarkdown c --pretty` — Produces indented, readable output code (for debugging; avoid in production). ```bash quarkdown c main.qd --pretty ``` `quarkdown c --timeout ` — Maximum total runtime. Default: 30 s; `0` disables the limit. ```bash 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. ```bash quarkdown c main.qd --forbid-function-overwriting ``` `quarkdown c --no-media-storage` — Turns off the media storage system. ```bash quarkdown c main.qd --no-media-storage ``` `quarkdown c --subdoc-naming ` — Naming strategy for subdocument outputs: file-name (default), collision-proof, document-name. ```bash quarkdown c main.qd --subdoc-naming collision-proof ``` `quarkdown c -l ` — Directory to load external libraries from. Default: `/lib/qd`. Long: --libs ```bash quarkdown c main.qd -l ./libs ``` `quarkdown c -Dloglevel= …` — Sets the log level (JVM property). At `warning` or higher, the output content is no longer printed. ```bash quarkdown c main.qd -Dloglevel=warning ``` ## Web server `quarkdown start -f ` — Starts the web server pointing at the given file (mandatory option). Required to preview `paged` documents. ```bash quarkdown start -f quarkdown-output/ ``` `quarkdown start -f -p ` — Starts the web server on a specific port. Default: 8089. ```bash quarkdown start -f quarkdown-output/ -p 9000 ``` `quarkdown start -f -b ` — Opens the served page in the given browser. ```bash quarkdown start -f quarkdown-output/ -b chrome ``` ## REPL & diagnostics `quarkdown repl` — Opens an interactive REPL to experiment with Quarkdown. ```bash quarkdown repl ``` `quarkdown doctor env` — Checks the external runtimes (JVM, Node.js, Puppeteer). ```bash quarkdown doctor env ``` `quarkdown doctor get install-dir` — Prints the absolute path of the install directory (handy in shell scripts). ```bash INSTALL="$(quarkdown doctor get install-dir)" ``` `quarkdown doctor get agent-skill` — Prints the path to the bundled AI agent skill (contains SKILL.md). ```bash 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. ## Further reading - [Quarkdown wiki: CLI options](https://quarkdown.com/wiki/cli-options) – the full reference of all compiler and REPL options - [Quarkdown wiki](https://quarkdown.com/wiki) – getting started, quickstart and language reference - [Standard library](https://quarkdown.com/docs/) – every function with signature and return type