# Quarkdown: When Markdown Learns Typesetting

> Quarkdown is a Markdown superset with functions, variables and scripting — a readable LaTeX that turns one source into a web page, PDF, book or presentation. The start of a series.

Source: https://www.jpkc.com/db/en/blog/quarkdown-einstieg/

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:

```markdown
.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:

```markdown
.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](https://typst.app/), 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:

```shell
brew install quarkdown-labs/quarkdown/quarkdown
```

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

```shell
quarkdown create my-document
```

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

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

```shell
quarkdown c main.qd -p -w
```

If you work in VS Code, the official [Quarkdown extension](https://marketplace.visualstudio.com/items?itemName=quarkdown.quarkdown-vscode) 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.

## Further reading

That was the overview. In the next parts of this series I go deeper: **functions, variables and scripting** (the "Turing-complete" promise made concrete), **document types, themes and layout**, **data, tables and diagrams**, **academic writing** with bibliography and cross-references, the **path to the artifact** via CLI, PDF and deployment, and the **AI angle** around the bundled agent skill. If you'd rather not wait, the full reference is in the [official Quarkdown wiki](https://quarkdown.com/wiki) and the [standard library](https://quarkdown.com/docs/).