Quarkdown: Arranging Content — Stacks, Containers, Boxes & Grids

Markdown can do a lot, but one thing it never could: arrange content side by side. Two columns, an image gallery, a business card, a grid of tiles — for that you used to reach for raw HTML. Quarkdown turns layout into functions. Part 3 was about the document as a whole; now we arrange content within the page. The tools are few — and a single detail decides whether they work.

Stacks: rows, columns, grids

The three stack functions arrange a group of elements by a layout rule:

.row — side by side
.column — stacked vertically
.grid — in a grid (requires columns:{n})

.row gap:{1cm}
    A

    B

    C

All three accept alignment (main axis: start, center, end, spacebetween, spacearound, spaceevenly), cross (cross axis: start, center, end, stretch) and gap (spacing). .grid additionally knows vgap/hgap for separate vertical and horizontal spacing.

The most important rule: the blank line

Stack functions work with the strict Markdown concept of a block — an isolated chunk of the document: a paragraph, a code block, a list, an image, a function call. From this follows the most common pitfall of all:

.row gap:{1cm}
    A
    B
    C

This produces one column, not three — because A B C without blank lines are a single paragraph. Only the blank line between the elements turns them into separate blocks. Once you've internalized this, you've saved yourself most layout frustration.

Containers: reset the layout and style it

What if an element itself consists of several blocks — say a heading and text in one column? Then you need the .container. It groups any number of blocks into one unit and resets the layout rules back to the normal document flow:

.row alignment:{center} gap:{1cm}
    .container
        ##! Left
        Text of the left column.

    .container
        ##! Right
        Text of the right column.

Beyond that, .container is Quarkdown's most flexible styling building block: width, height, fullwidth, foreground, background, border/borderwidth/borderstyle, margin, padding, radius, alignment and a whole range of font parameters (fontsize, fontweight, fontstyle, fontvariant, textcase …). With classname you attach your own CSS class.

.container fullwidth:{yes} borderstyle:{dashed} padding:{1cm} fontstyle:{italic} fontvariant:{smallcaps}
    A styled container. Fancy, isn't it?

Boxes: typed callouts

The .box is a special container with an inline title and block content — the classic for hints, tips and warnings. Five types are available: callout (default), tip, note, warning, error.

.box {Attention} type:{warning}
    This is something you shouldn't overlook.

A nice detail: if you omit the title and have set .doclang, Quarkdown localizes the title automatically — a type:{tip} box reads "Tip" in English, "Tipp" in German. That's exactly how I built a custom .example function in the quickstart example from part 1 — it's nothing but a preconfigured box.

More layout building blocks

Quarkdown ships further ready-made building blocks I'll only touch on here: .align and .float for alignment and wrapped elements, .clip for clipping (e.g. circular images), .collapsible for collapsible sections, .filetree for directory trees (which I've used several times in this series) and .whitespace for deliberate empty space. All follow the same pattern: one function call, one indented body. The full reference is in the layout section of the wiki.

FAQ

Why does my `.row` appear as a single column?

Almost always the blank line between elements is missing. Without it they merge into one paragraph, which the stack treats as one block. A blank line between each pair of items fixes it.

When `.container`, when `.column`?

.column is a layout rule (stacks elements vertically with spacing). .container is the opposite — it lifts layout rules and bundles several blocks into one unit. If you want multiple multi-part contents side by side in a row, .container is the right tool.

Can I nest stacks?

Yes, arbitrarily. .row in .column in .grid — that's how you build business cards, dashboards and complex page grids out of the same three building blocks. This composition is exactly what makes Quarkdown powerful.