8.2 – A docs site

Documentation with a few sections, each with some chapters:

index.md
getting-started/ index.md, installation.md, first-steps.md
guides/          index.md, import/…, export/…
reference/       index.md, cli.md, configuration.md

The four entries

plugins:
  # 1 · Header: the sections, their pages in the menu, behind the burger button on smartphones
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: dropdown
      depth: 2
      trigger: hover
      folderClick: link
      mobile: offcanvas
      ariaLabel: Sections
      id: header
    layout:
      position: header
      priority: 20
 
  # 2 · Sidebar: only the section you are reading
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: accordion
      scope: section
      showScopeRoot: true
      persistState: true
      mobile: hidden
      ariaLabel: This section
      id: section
    layout:
      position: left
      priority: 20
 
  # 3 · Below the text: paging, but not beyond the section
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: pager
      scope: section
      id: pager
    layout:
      position: afterBody
      priority: 10
 
  # 4 · Footer: the whole site in columns
  - source: github:boxi-os/quartz-navigations
    enabled: true
    options:
      variant: columns
      depth: 2
      mobile: accordion
      ariaLabel: Sitemap
      id: sitemap
    layout:
      position: footer
      priority: 10

Why like this

Every navigation has one job. The header says which sections exist. The column says where you are within a section. The pager says what comes next. The footer is where you look when you are lost.

Header: depth: 2 keeps the menu flat — sections and what they contain. Subfolders such as import appear as a row linking to their folder page, their pages do not. hover with link opens on hover and leads to the section page on click (5.2). On smartphones the whole bar becomes a burger menu.

Column: scope: section shows only guides while you read the guides. The start page has no section; the column stays empty there, and that is right — the header shows all sections. mobile: hidden, because the burger menu does the same job on smartphones.

Pager: with scope: section, paging ends at the last chapter of the section instead of silently jumping into the next one.

Footer: mobile: accordion collapses the columns into a list on smartphones whose sections can be opened.

ariaLabel everywhere except on the pager, because three of the four <nav> would otherwise be called “Main navigation”; the pager is called “Previous and next page” on its own (7.3).

And the explorer?

Switch it off — enabled: false on the @quartz-community/explorer entry. The column takes over its job for the current section, the header for the rest.

Variations

If …	then …
the sections have many subfolders	header as mega with depth: 3
there are only three or four sections and you should see which one you are in	header as tabs, no menu then
the order of the sections should not be alphabetical	order: { "": [getting-started, guides, reference] } in all entries, or navOrder in the index.md files
the pager should lead through the whole documentation	leave out scope on the pager