Quarkdown: Tips & Tricks from Practice

To close the series I collect the touches that appeared only in passing in the previous ten parts — the small things that make everyday work with Quarkdown noticeably easier. After the look into the pipeline, it gets practical and compact once more.

The blank line is sacred

By far the most common pitfall, so first: stack functions like .row separate elements by block — and blocks are formed by blank lines. A, B, C without blank lines between them are one paragraph and yield one column. Always put a blank line between the items. (More on this in part 4.)

Readability: chaining and line continuation

Nested calls turn from inside-out to left-to-right with :: — .pow {3} {2}::subtract {1}::sum {2} reads like mathematics. And when a call has many arguments, a backslash at the end of the line breaks the argument list cleanly:

.container alignment:{center} \
           background:{red} \
           padding:{1px}

Function calls in the middle of a word

A call directly adjacent to a word character isn't normally recognized. Wrap it in curly braces and it can go anywhere — the braces vanish from the output:

H{.text {2} script:{sub}}O

Compact footnotes

Instead of separating reference and definition, you can define a footnote right where you reference it:

… and much more[^: All Markdown features are supported].

Living code blocks

The .code function is the dynamic sibling of the triple-backtick block: it evaluates its body as Quarkdown. Combined with .read you load a snippet from the real source file — so the block stays automatically in sync with the code it shows:

.code lang:{typescript} focus:{5..8}
    .read {assets/point.ts}

focus:{5..8} highlights a line range, linenumbers:{no} turns off numbering. For inline code with function evaluation there's the analogous .codespan.

Computing CSV tables

.csv with mode:{markdown} interprets cell content as inline Quarkdown — so tables compute themselves at compile time and stay in sync with the data source (see part 5). An underrated lever for reports that update with the data.

Text symbols for free

Quarkdown replaces common symbols automatically in running text (not in code/math/URLs): -- becomes —, -> becomes →, >= becomes ≥, != becomes ≠, (C) becomes ©, (TM) becomes ™, and straight quotes become typographic ones. If a character should not be replaced, prefix it with a backslash: \->.

Small helpers: collapse and icons

.collapse {Title} creates a collapsible block — ideal for FAQ-style details or long examples; open:{yes} starts it open. And .icon {github} places a pixel-perfect Bootstrap icon right in the text.

Decorative headings

A heading with ! (i.e. ##! instead of ##) is not numbered and not included in the table of contents — handy for subtitles inside layout blocks that don't belong in the outline.

Your own mini library

You don't have to copy recurring functions into every document. Put them in a separate .qd file and include it via .include {name} (without extension) — just like the built-in paper library from part 6. That turns your building blocks into a reusable style library.

And always: --strict

In normal operation Quarkdown renders errors as boxes into the document — handy while writing, dangerous in production. So --strict belongs in every automated build, so that an error aborts the build hard instead of slipping through silently.

FAQ

What's the one tip I should remember?

The blank line. It feels like nine out of ten "why does this look wrong?" moments in Quarkdown come down to a missing separating blank line between two blocks.

How do I organize a larger project?

Separate setup and content (.include {setup.qd}), move recurring components into a dedicated library .qd, and use subdocuments for knowledge bases. That keeps even a large document maintainable.

Where do I find all the functions?

In the standard library — it lists every function with signature, parameters and return type. For conceptual explanations, the wiki is the right place.

The series at a glance

With that, the series is complete. It leads from the introduction through scripting, document types & themes, layout, data & diagrams, academic writing, presentations, CLI & deployment and the AI part all the way behind the scenes. The full reference remains the official wiki.