Quarkdown: A Markdown Typesetting System That Compiles One Source to Papers, Slides and Books

The problem Quarkdown takes on: one source, many output formats

Most Markdown toolchains pick a lane. A static site generator produces HTML. A slide tool produces slides. A PDF pipeline wraps a separate typesetting engine. If you want a paper, a presentation and a wiki page that share the same prose, you maintain three sources and reconcile them by hand.

Quarkdown's stated goal is to remove that split. The README describes it as a "modern Markdown-based typesetting system designed for versatility" and says a single project can compile into a print-ready book, academic paper, knowledge base or interactive presentation. The audience is people who already write in Markdown and want document-level control over layout without moving to LaTeX or Typst syntax.

The comparison table in the README positions it against LaTeX, Typst, AsciiDoc and MDX on three axes: concise and readable syntax, full document control, and scripting. Quarkdown claims all three. That combination is the actual pitch, and it is also where the interesting trade-offs live, because scripting inside a document format changes what a document is.

How Quarkdown works: functions, targets and a permission system

Quarkdown is built as an extension of CommonMark and GFM. The extension, called the Quarkdown Flavor, adds function calls to Markdown. The README gives the shape directly: a dot-prefixed name, then brace-delimited arguments, then an optionally indented body argument.

.somefunction {arg1} {arg2}
    Body argument

Functions can be defined by the author, not just called. The README's example defines a greet function with named parameters to and from, then invokes it, producing "Hello, world from iamgio". The repository ships a standard library in quarkdown-stdlib covering layout builders, I/O, math, conditionals and loops, and the README calls the extension Turing-complete. That is the mechanism: a Markdown file is parsed, functions are resolved and executed, and the result is rendered to a target.

The target is chosen inside the document with the .doctype function. The README lists .doctype {plain} as the default, plus {paged}, {slides} and {docs}. Plain HTML produces a continuous flow the README compares to Notion or Obsidian. Paged HTML goes through paged.js and is aimed at papers, articles and books. Slides go through reveal.js. Docs is aimed at wikis and large knowledge bases. PDF export is described as supporting everything the HTML targets support, and GFM export and plain text are also listed.

The repository layout matches that pipeline. There are separate modules for quarkdown-core, quarkdown-html, quarkdown-html-pdf, quarkdown-markdown, quarkdown-plaintext, quarkdown-stdlib, quarkdown-server and quarkdown-lsp. The LSP module is what backs the editor extensions, and the server module is what a live preview would talk to.

Security is handled by what the README calls a restrictive permission system that limits access to system resources. That matters more here than in a normal Markdown tool, because a Turing-complete document can call I/O functions. The README states the default is restrictive; it does not enumerate the permission names or their defaults.

Installing Quarkdown and compiling a first document

The README points to quarkdown.com/wiki for getting started rather than embedding install commands in the repository README, so the canonical setup instructions live there. What the repository does contain is a Dockerfile, which builds a distribution zip with Gradle and runs the CLI from a headless Chrome base image.

The build stage uses Gradle 8.14.3 on JDK 17, installs nodejs and npm, and runs the distZip task. The runtime stage is based on chromedp/headless-shell, and the Dockerfile sets two environment variables before the entrypoint:

ENV QD_CHROME_PATH="/headless-shell/headless-shell" \
    QD_NO_SANDBOX="true"

ENTRYPOINT ["quarkdown"]

QD_CHROME_PATH tells Quarkdown where the headless browser lives, and QD_NO_SANDBOX disables the browser sandbox, which is common in containers. The image also installs ca-certificates, fontconfig and fonts-liberation, and runs as a non-root quarkdown user. Note that the headless shell version is pinned as a build argument, HEADLESS_SHELL_VERSION=151.0.7922.109, and the comment says it must stay in sync with quarkdown-html-pdf/scripts/chrome.properties and the installers. That pin is the thing to watch when PDF output breaks.

The repository also contains a demo directory with demo/demo.qd, plus demo/code/, demo/csv/, demo/img/, demo/mermaid/ and demo/sources/. Those are the files to compile first if you want to see how a real document is structured, including how code, CSV data and Mermaid diagrams are pulled in.

For a first real use, the smallest meaningful step is a document that sets its own type. The README gives the exact call:

.doctype {paged}

Placing that at the top of a source file switches the output from the default continuous plain HTML to paged HTML, which is the mode intended for papers and books. If you then export to PDF, the headless Chrome path in QD_CHROME_PATH is what gets used, so a container run and a local run can behave differently depending on how that variable is set.

Where Quarkdown stops being the right tool

The clearest limitation is release discipline. The repository is not archived, but the latest release is tagged "Development build" and dated 2025-05-13, while the stable line sits at v2.5.1 from 2026-08-12. Anyone who installs by following the "Latest" link in the README badge gets the development build, not the stable one. The README presents both, and the distinction matters if you are putting this in a build pipeline.

PDF output is the second constraint. It depends on a headless browser, and the Dockerfile pins that browser to an exact version that must be kept in sync across three places: the Dockerfile argument, quarkdown-html-pdf/scripts/chrome.properties, and the installers. That is a maintenance surface a pure Markdown-to-HTML tool does not have. If your environment cannot run a headless Chrome, or you need PDF generation with no browser dependency, this is the wrong pipeline.

The permission system is a third area to probe. The README calls it "secure by default" and says it limits access to system resources, but it does not list the permission identifiers or explain how to grant them. Since the language is Turing-complete and the standard library includes I/O, the practical question of what a document is allowed to touch is answered in the wiki, not in the README. Treat that as documentation you must read before running untrusted .qd files.

Finally, the scripting is a double-edged design choice. Function definitions and loops make repeated content a one-line call, which is the stated benefit. They also mean a Quarkdown source is a program, and a program can fail in ways prose cannot. If your team's review process assumes documents are inert text, that assumption no longer holds.

Quarkdown against Typst and LaTeX

The README's own comparison table is the fairest starting point. Against LaTeX, Quarkdown claims the advantage on concise, readable syntax, and LaTeX is marked as failing that column. Against Typst, the two are marked equal on readability and document control. Against AsciiDoc and MDX, Quarkdown claims full document control where both are marked as lacking it.

The real difference with Typst is the input language. Typst uses its own markup and scripting syntax with a Rust implementation. Quarkdown keeps CommonMark and GFM as the base and layers functions on top, so an existing Markdown file is closer to being valid input. If your content already lives in Markdown and you want to avoid a conversion step, that is the concrete advantage.

The real difference with LaTeX is the learning curve and the ecosystem. LaTeX has decades of packages and journal templates; Quarkdown has a standard library in quarkdown-stdlib and a wiki. If a publisher requires a specific LaTeX class file, Quarkdown cannot substitute for it.

MDX is the closest comparison in spirit, since both let you embed executable logic in Markdown. MDX targets the JavaScript and React ecosystem and produces components for web rendering. Quarkdown targets document output: paged HTML, slides, docs, PDF and GFM. If your destination is a website built with a JS framework, MDX fits. If your destination is a printable document, Quarkdown's .doctype {paged} path is the one built for it.

Licence, upgrade cost and what a fork implies

Quarkdown is licensed under GPL-3.0. That is a copyleft licence, and it is worth noting because this project is a compiler and a language runtime rather than a library you link against. The practical consequence is that if you distribute a modified Quarkdown, the modified source has to be made available under the same terms. Running it to produce your own documents is a different activity from redistributing a modified binary, and the LICENSE file in the repository root is the authoritative text. This is not legal advice; if you plan to embed Quarkdown in a product you ship, take it to someone qualified.

Upgrade cost is shaped by the module split. quarkdown-core, quarkdown-html, quarkdown-html-pdf, quarkdown-markdown, quarkdown-plaintext and quarkdown-stdlib are separate Gradle modules in one repository, so a change to the standard library or the HTML renderer lands in the same commit stream as the CLI. There is a CHANGELOG.md at the root, which is where to look before bumping a version. The pinned headless shell version is the upgrade step most likely to require manual attention, because it is duplicated across the Dockerfile and the PDF module's properties file.

Language-level changes are the other cost. If you define your own functions in a document, a change to how arguments or bodies are parsed can break your source. Version pinning is the mitigation, and the existence of a separate stable release line at v2.5.x is what makes that possible.

Editorial conclusion

Adopt Quarkdown if you write long documents in Markdown and want paged output, slide decks and a knowledge base from one source, and you are willing to track a project whose most recent release is a development build. Do not adopt it if you need a documented stability guarantee or a release train you can pin for years. Before committing, compile your own document with .doctype {paged} and check the PDF export path, since PDF depends on a bundled headless Chrome whose version is pinned in the Dockerfile and in quarkdown-html-pdf/scripts/chrome.properties.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes