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.

Layout Box

3 Min. Lesezeit

quartz-layout-box puts a piece of HTML or Markdown anywhere in the Quartz layout: into a sidebar, the header, the footer, before or after the page body. A word mark, a subtitle, a notice, a call to action, a line stating where the page stands — anything meant to look the same across many pages without being written into a theme.

What it does

Anywhere on the page

Header, both sidebars, before and after the text, footer — and as often as you like: every entry is a box of its own with its own options. → 3

HTML or Markdown, from a file or straight from the configuration

A Markdown snippet is turned into HTML at build time. Kept as a file, a change shows in the preview on the next reload, without a restart. → 2

Placeholders

The page title, the site title, the page’s path, the way back to the start page and any frontmatter field can be filled in — one box that says something different on every page. → 4

Heading, collapsing, a class of its own

A box can carry a heading and collapse and expand, without any JavaScript. A class of its own is what you style it by; images come in one variant per colour scheme. → 5

Controllable per page

A single page hides the box through its frontmatter, or swaps the snippet and the heading. → 6

Its own text in every language

With byLang every language gets its own file, its own text and its own heading — made to go with quartz-multilanguage. → 7

The plugin works entirely at build time and ships no JavaScript to the browser.

This site is its own evidence

It is built with the plugin. The word mark at the top left, the chapter name beside it and the box at the bottom of the left column are three layout boxes; chapter 8 takes each of them apart.

The nine chapters

ChapterThe question it answers
1 – Getting startedWhat is the plugin for, and how does the first box appear?
2 – The snippetFile or configuration, HTML or Markdown?
3 – PlacementWhere may a box sit, and in what order?
4 – PlaceholdersHow does the page title get into the box?
5 – FormHeading, collapsing, your own class — and how to style it
6 – Per pageHow does a single page hide or swap the box?
7 – Two languagesHow does each language get its own text?
8 – RecipesFinished examples, all visible on this page
9 – ReferenceEvery option, every message, the glossary

In one minute

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

Create a snippet at quartz/static/snippets/snippet.html, add the entry to quartz.config.yaml, done:

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

At length under 1.2 – Your first box.

Where else it is written

The short version is the repository README — the same options, without examples. The plugin belongs to QuartzControl, where it can be set up without writing YAML; the app is not required, though.

9 Dateien in diesem Ordner.