Quarkdown: When Markdown Learns Typesetting

Markdown is the lingua franca of the writing web — easy to learn, readable everywhere, quick to type. And yet it keeps hitting the same wall: the moment a document wants more than flowing text with a few headings — an image size, a numbered figure, a table of contents, a centered block, the same building-block logic in twenty places — it turns into a craft project of raw HTML and copy-paste. Quarkdown is the answer to exactly that: a superset of Markdown that adds functions to the familiar syntax and, from a single source, produces a web page, a PDF, a print-ready book or an interactive presentation. Its author aptly calls it "a more readable LaTeX." This article opens a series in which I work through the tool from the ground up — today: what Quarkdown actually is, and why it's worth a look.

The core idea: functions in Markdown

Quarkdown builds on CommonMark and GitHub Flavored Markdown. Everything you know from Markdown still works: **bold**, *italic*, lists, links, tables, code blocks. The decisive addition is a single new idea — the function call. It starts with a dot, and arguments go in curly braces:

.center
    This paragraph is now centered in the document.

The indented "body argument" is the content the function acts on. Function calls can be chained — the output of one becomes the input of the next:

.sqrt {10}::round::multiply {2}

Everything else grows out of this small mechanism: layout builders, mathematics, loops, conditionals, your own reusable components. In that sense Quarkdown is Turing-complete — a genuine little programming language disguised as Markdown. An image size is written as !(50%)[Logo](logo.png) instead of an HTML <img> with an inline style. Recurring content — a callout box, a letterhead, a piece of formatting — you define once as a function and then call with a single line. The details on variables, custom functions and scripting I'm saving for part 2 of the series; here it's about the big picture.

One source, four outputs

The real trick is versatility: the same .qd source can render to four different document types, controlled by a single line at the top of the document:

`.doctype`	Character	Ideal for
`plain`	continuous flow like Notion/Obsidian	websites, knowledge management
`paged`	classic pages with breaks (via paged.js)	articles, academic papers, books
`slides`	interactive presentation (via reveal.js)	talks
`docs`	sidebar plus table of contents	wikis, technical documentation

All four HTML variants can additionally be exported as PDF; on top of that there's a plain text output. The promise, then, is: write once, output differently depending on the target — from a blog post to a bound book, without touching the content. The official Quarkdown wiki, with its 100-plus pages, is itself a docs document and compiles in about two seconds.

Where Quarkdown sits

Quarkdown plays in the same field as LaTeX, Typst, AsciiDoc and MDX — and deliberately positions itself in between: the full document control and scripting of a LaTeX, but with the flat learning curve of Markdown. The comparison from the project docs sums it up:

	Quarkdown	LaTeX	Typst	AsciiDoc	MDX
Concise & readable	✅	❌	✅	✅	✅
Full document control	✅	✅	✅	❌	❌
Scripting	✅	partial	✅	❌	✅
Book/article export	✅	✅	✅	✅	third-party
Presentation export	✅	✅	✅	✅	third-party
Static-site export	✅	❌	experimental	✅	✅
Docs/wiki export	✅	❌	❌	✅	✅
Learning curve	low	high	medium	low	low
Targets	HTML, PDF, TXT	PDF, PS	HTML, PDF	HTML, PDF, ePub	HTML

Anyone who has ever typed a LaTeX figure environment with three subfigure blocks knows why the Markdown-like style appeals: the same result takes a fraction of the characters in Quarkdown — and stays readable.

Your first document in three commands

One thing for context up front: Quarkdown is a local command-line tool, not an online service or web app. You install it and work through the quarkdown command — the actual engine is a JVM library, the CLI its main interface. An official VS Code extension and a language server sit on top as a convenience layer, but drive the same compiler under the hood. So there's no server-side editor; the result is static HTML (or PDF) that you place yourself.

Quarkdown installs quickly — on Linux and macOS via a script or Homebrew, on Windows via a script or Scoop:

brew install quarkdown-labs/quarkdown/quarkdown

After that, an interactive wizard scaffolds a new project including metadata and starter content:

quarkdown create my-document

You compile with quarkdown c — the HTML output lands in the output directory, and a --pdf additionally produces the PDF:

quarkdown c main.qd

And for working on the text there's a low-latency live preview: -p (preview) opens the browser, -w (watch) recompiles on every file change.

quarkdown c main.qd -p -w

If you work in VS Code, the official Quarkdown extension gives you the same preview at the press of a button. Another plus for security-conscious setups: Quarkdown is secure by default — a restrictive permission system limits access to system resources out of the box.

Why this is here

This platform is itself an experiment in keeping content machine- and AI-friendly — every page is also available natively as Markdown. Quarkdown hits the same nerve from the other side: it takes Markdown seriously enough to produce professional artifacts from it, and explicitly markets itself as agent-friendly — it ships its own skill for AI coding agents so they handle the format fluently. I'll devote a dedicated part of the series to exactly this AI angle later on. Quarkdown is open source (GPLv3; CLI and Language Server under AGPLv3) and is maintained by the developer iamgio.

FAQ

Does Quarkdown replace my normal Markdown?

No — it extends it. Every valid CommonMark/GFM document is already valid Quarkdown. You can start small and use functions only where plain Markdown no longer suffices. For a README or a GitHub issue, plain Markdown remains the right tool; for a print-ready document, Quarkdown plays to its strengths.

Do I need to know LaTeX?

No. That's precisely the point: Quarkdown aims for the flat learning curve of Markdown, not the steep one of LaTeX. You can embed TeX formulae, but you don't have to — the rest of the document stays familiar Markdown syntax with a few .function calls.

What do I need for PDF export?

PDF export builds on Node.js and Puppeteer, because it renders the HTML output through a browser engine in the background. That makes it a bit slower than plain HTML compilation, but it delivers pixel-for-pixel the same result as the web preview.