English
About this handbook

This handbook belongs to the Quartz plugin quartz-navigations. And it is built with it: the menu above and the previous/next links below every text come from there.

What the entries behind them look like is explained in 8.1.

Navigations

3 Min. Lesezeit

Quartz ships one navigation: the explorer, a folder tree in the sidebar. That’s it. quartz-navigations builds every other navigation a website needs from the same folder structure — a menu bar in the header, an accordion for the current section, a sitemap in the footer, “previous” and “next” below the text. One plugin, as many entries as you like, and each one chooses which part of the tree it shows and in what form.

What it does

From the folder structure

The tree is built from the content’s folders at build time. Titles come from a folder’s index.md or its name, the order by hand, alphabetically or by date. → 2

As often as you like, each with its own scope

One plugin, as many entries as the site needs. Each shows the whole site, one section, the current folder or only the siblings — and as many levels as it should. → 3

Ten variants

Tree, accordion and flyout for the sidebar; bar, dropdown, mega menu and tabs for the header; columns for the footer; a jump menu, and previous/next below the text. → 4

On smartphones

Every navigation decides for itself what becomes of it below the mobile breakpoint: it stays, turns into an accordion, goes behind a burger button, becomes a jump menu or disappears. → 6

Without JavaScript, and usable by everyone

The navigation is finished in the HTML; a small script adds remembered folders, menus that open on hover and the scroll lock behind a mobile menu. Whole rows are click targets, aria-current marks the page, and a screen reader hears the words in the page’s language. → 5, 7.3

Looks like the rest of the site

Colours, fonts and dark mode come from the theme; every value is a --quartz-nav-* variable. Folder and page glyphs like a file manager, your own icon per page from Lucide. → 7

With quartz-multilanguage one entry shows every page the tree of its own language, however the languages are laid out in the content (8.3).

This website is its own proof

It is built with the plugin. The menu in the left column, which becomes a drawer on smartphones, and the previous/next links below every text are two entries of the plugin. 8.1 shows them and explains every option.

The nine chapters

ChapterThe question it answers
1 – Getting startedWhy the plugin, and how does the first navigation come about?
2 – The treeWhere do titles and order come from, and what is left out on purpose?
3 – The scopeThe whole site, one section or just the current folder?
4 – The ten variantsTree, bar, accordion, menu, columns, pager — which one for what?
5 – InteractionWhat happens when a folder is clicked, and what on hover?
6 – MobileWhat becomes of a menu bar on a smartphone?
7 – AppearanceIcons, colours, spacing — and how to change them
8 – RecipesFinished combinations, one of them on this page
9 – ReferenceEvery option, every message, every limit

In one minute

npx quartz plugin add github:boxi-os/quartz-navigations

Then one entry per navigation. This one puts the first folder level into the header as a bar:

plugins:
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: bar
      depth: 1
      mobile: offcanvas
    layout:
      position: header
      priority: 20

The details are in 1.2 – Your first navigation.

Where else it is written down

The short version is the repository README. The sister plugins quartz-layout-box and quartz-multilanguage work together with this one; all three belong to QuartzControl, but the app is not required.

9 Dateien in diesem Ordner.