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.3 – What happens at build time

2 Min. Lesezeit

Quartz loads the plugin as a pure component. Every entry in quartz.config.yaml that has a layout block becomes its own instance with its own options. An entry without a layout block does not disappear: Quartz places any component that names no position at its manifest’s default — for this plugin left, with priority: 15. Building each page then runs the same sequence:

  1. Check the frontmatter — is the box hidden on this page? Was a different snippet chosen? Does the page have a language that byLang knows something about?
  2. Determine the source — html from the configuration wins, otherwise the file from dir and file.
  3. Read the file — the path has to lie inside dir. Reading is cached: reloaded only when the modification time has changed.
  4. Render Markdown — if the file ends in .md, it becomes HTML. That result is cached too.
  5. Replace placeholders — page and site values are inserted and escaped along the way.
  6. Emit — a div with the class layout-box, optionally with a heading or as a collapsible details.

Why reloading works without a restart

Step 3 asks for the file’s modification time on every render. If it is the same as last time, the content comes from the cache; if it is newer, the file is read.

So a change to the snippet takes effect immediately under --serve, and it needs no file watcher that somebody would have to set up and tear down. In a normal build the same approach costs exactly one filesystem stat per page — measurable, but weightless next to the rest of a build.

What follows from that

The cache hangs on the modification time, not on the content. Writing a file back with the same timestamp — restoring from an archive, say — shows the old version until the time changes.

A pure component, not a transformer

The plugin does not reach into the content pipeline. It sees no note, changes no text and never walks the vault. It is asked only when Quartz assembles the layout of a page.

That is why a Markdown snippet resolves no wikilinks: the place where Quartz does that sort of thing is long behind the box.