1.2 – Your first box

Four steps, and the box is there.

1. Install the plugin

npx quartz plugin add github:boxi-os/quartz-layout-box

The command fetches the plugin and adds it to quartz.config.yaml. In QuartzControl the same happens through the marketplace.

2. Create a snippet

The file goes into quartz/static/snippets/ — that folder belongs to the site, not to the content. It is created if it is missing:

<!-- quartz/static/snippets/snippet.html -->
<p>Notes from a small town.</p>

3. Add the entry

plugins:
  - source: github:boxi-os/quartz-layout-box
    enabled: true
    options:
      file: snippet.html
    layout:
      position: left
      priority: 15

position says where, priority in what order within that place — smaller means further up. Both are explained in chapter 3.

It works without options too

Then the defaults apply: the file snippet.html in the folder quartz/static/snippets.

4. Look at it

npx quartz build --serve

The box sits in the left column. Change the snippet file now and a reload is enough — no restart of the server. Why that works without a watcher is under 1.3 – What happens at build time.

When nothing appears

What you see	What causes it
A dashed box with a path in it	The file is missing at exactly that place. The box only appears in serve mode; in a normal build the box stays empty and the console says so once.
Nothing at all, no message	The snippet is empty. A box without content outputs nothing — not even an empty div.
Nothing, but a warning during the build	The path leads out of dir. The plugin refuses that; see 2.2 – Where the file comes from.
The box is there, in the wrong place	position or priority — 3.2 – The order.