Quarkdown 2.4: flexibility as a first-class citizen

2.4 marks one of the most impactful releases Quarkdown has ever faced, with the core concept being: “you can now extend Markdown itself.” Similar to Typst’s #show rules, you can think of this feature as CSS that rewrites the AST, written in Quarkdown itself.

For more detailed and up-to-date information, check out the wiki page on element styling.

Primitives

Several Markdown elements now have a matching function behind them, called a primitive:

• .heading backs #, ##, …
• .paragraph backs plain paragraphs
• .link backs [label](url)
• .math backs $ ... $ and $$$ ... $$$
• .image and .figure back ![label](url)
• .pagebreak backs <<<

Most of them also inherit .container’s styling options, such as foreground, background, border, padding and fontsize.

Extending a primitive

.extend was first introduced in 2.2 as a way to override user-defined functions. Because this update directly binds Markdown elements to their primitives, extending a primitive function allows intercepting and overriding the default behavior of its corresponding Markdown element.

.extend {heading}
    content:
    .super foreground:{blue}
        *.content*

## A section heading

The previous snippet restyles every heading in the document to have blue text and italics, by calling .super — the original function — called with the overridden arguments.

Conditional extension

The new where parameter lets a wrapper fall through to the original when a condition isn’t met. The following snippet styles H1 and H2 to have blue text, while H3 and lower headings remain unaffected:

.extend {heading} where:{depth: .depth::islower than:{3}}
    .super foreground:{blue}

# Top-level heading
## Section heading
### Subsection heading

The following snippet adds an external-link icon to every link that isn’t internal (doesn’t start with https://quarkdown.com):

.extend {link} where:{url: .url::startswith {https://quarkdown.com}::not}
    content:
    .super
        .content .icon {box-arrow-up-right}

Check out the [wiki](https://quarkdown.com/wiki)
and the [repo](https://github.com/iamgio/quarkdown) to get started.

Matching against patterns

.match scans inline content for regex hits and replaces each one with the output of a lambda:

.match {Quarkdown takes its name from quarks} pattern:{[Qq]uark(down|s)?}
    ***.1***

Pair it with paragraph extension to highlight every occurrence of a pattern across the document:

.extend {paragraph}
    content:
    .super
        .content::match {[Qq]uark(down|s)?}
            ***.1***

Quarkdown is a typesetting system that borrows its name from quarks,
which are elementary particles in physics and include:
up quarks, down quarks, strange quarks, charm quarks,
top quarks and bottom quarks.

Status

Primitive extension ships as slightly experimental with a deliberately small set of primitives. The plan is for every Markdown element to eventually be backed by a primitive, if this feature proves stable.

Any feedback, bug reports and enhancement requests are welcome via issues.

Get Quarkdown, or read the full release notes.