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

> Part 4 of the Quarkdown series: how to arrange content on the page with .row, .column, .grid, .container and .box — and why the blank line is what decides it.

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

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](https://www.jpkc.com/db/en/blog/quarkdown-dokumenttypen-themes/) 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}`)

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

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

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

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

```markdown
.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](https://www.jpkc.com/db/en/blog/quarkdown-einstieg/) — 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](https://quarkdown.com/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.

## Further reading

The framing is set by [part 3: Document Types, Themes & Page Setup](https://www.jpkc.com/db/en/blog/quarkdown-dokumenttypen-themes/). Next it gets data-driven: **tables, CSV import and diagrams** — how Quarkdown automatically turns data into tables, XY charts and Mermaid graphics. The complete layout reference is in the [official wiki](https://quarkdown.com/wiki).