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.

7.1 – byLang

2 Min. Lesezeit

options:
  file: sidebar-note.md
  title: Über dieses Handbuch
  collapsible: true
  byLang:
    en:
      file: sidebar-note.en.md
      title: About this handbook

That is the entry the box at the bottom left of this site comes from — German as the base, English under byLang.

Where the language comes from

What is read is the page’s frontmatter field lang — the same field Quartz builds its <html lang> from. If the page has none, configuration.locale applies.

The plugin needs no further plugin for this. Whether lang is written by hand or set by a multilingual plugin makes no difference to it.

How the keys are matched

Case does not matter. The lookup happens in two passes:

  1. exact — en-US finds the entry en-US
  2. by the front part — en-US also finds the entry en

If nothing matches, the base options apply. Without a warning, because that is the normal case: a bilingual site names only the second language under byLang, and every page of the first quietly falls through to the base.

What can differ per language

Everything except two things: dir and frontmatterKey.

One is an installation path, the other the name a page uses to address the box — neither is a question of language. If the key changed per language, a translated page would have to write a different field than its original.

Forbidden here means: not intended

The TypeScript type does not allow those two under byLang — but a quartz.config.yaml is not type-checked. A byLang.en.dir therefore does take effect, measured. For frontmatterKey the sentence holds in practice as well: the key is read before byLang applies at all.

The order of precedence, in full

  1. the page’s frontmatter
  2. byLang for the page’s language
  3. the base options

Each level overrides only what it names. So the entry above keeps collapsible: true from the base options under en — only what differs is written there.

With one exception: html and file do not sit side by side, they sit against each other. An html on a weaker level beats any file on a stronger one — see the box in 6.1.