English
About this handbook

This handbook belongs to the Quartz plugin quartz-layout-box. And it is built with it: this box is a layout box.

It comes from a Markdown file, not from the configuration — which way is better when is in The snippet.

1.1 – Why this plugin

2 Min. Lesezeit

Quartz builds every page from components: explorer, table of contents, breadcrumbs, footer. Each has a job and fills itself from the content of the site. What does not exist is a component for this — the line under the site name, the logo, the notice that the site is still being built.

Without this plugin there are two ways to get one, and neither is good:

  • Write it into the theme. Then the text lives in a .tsx file, changing a comma needs a compile, and the next Quartz update collides with it.
  • Write it into every page. Then it sits in the vault 200 times and goes wrong 200 times as soon as anything changes.

The layout box is the third way: one snippet, maintained in one place, placed at one point in the layout.

What it does

It takes a piece of HTML or Markdown and puts it where you tell it — left or right sidebar, header, footer, before or after the page body. The text comes either from a file under quartz/static/snippets/ or straight from the configuration.

All of it happens at build time. What reaches the browser is finished HTML; the plugin ships no JavaScript, and a box costs the page nothing in load time.

What it does not do

It is not a building block for content. What belongs on one page belongs in that page. The box is for what is the same across many pages.

It does not render Obsidian syntax. A Markdown snippet does not go through Quartz’ content pipeline — wikilinks in double square brackets and callouts stay as written. Why that is, and what works instead, is under 2.3 – Markdown snippets.

And it filters nothing. A snippet is inserted as it stands; whoever embeds foreign HTML embeds foreign HTML. See 9.3 – Limits.

When it is worth it

The rule of thumb

As soon as the same piece of markup should appear on more than one page and is not part of the text, it belongs in a layout box.

Seven examples, all of them visible on this site, are in chapter 8. The shortest is the line in the footer carrying the site name; the most elaborate is the word mark at the top left, which switches between the light and dark colour scheme without a line of JavaScript being involved.