1.2 – Your first navigation

Three steps, and the navigation is there.

1. Install the plugin

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

The command fetches the plugin and adds it to quartz.config.yaml — with every option and its default value, as a tree in the left column (position: left, priority: 10). That is already a working navigation. The long list may be shortened: whatever is not there, the plugin assumes as its default.

In QuartzControl the same is done through the marketplace.

2. Write the entry

A short entry for a menu bar in the header:

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

• variant chooses the form — here a horizontal bar (chapter 4).
• depth: 1 shows only the first folder level (3.2).
• mobile: offcanvas turns it into a menu behind a burger button on smartphones (chapter 6).
• layout tells Quartz where the navigation goes. It is not part of the plugin but Quartz’s own mechanism for every component. Without the block the navigation does not disappear: Quartz puts it at the plugin’s default, left with priority: 10.

A second navigation is a second entry with the same source. More on that in 1.3.

3. Look

npx quartz build --serve

The bar sits in the header, the entry of the current page is highlighted, and every folder above it carries the active-trail mark. Below the site’s mobile breakpoint (6.2) the bar disappears behind a burger button.

When nothing appears

What you see	What causes it
Nothing, on no page, no message	enabled: false.
The navigation is on the left instead of where you wanted it	The layout block is missing or indented wrongly; the plugin’s default applies.
Nothing on some pages	rootPath is set and the page lies outside it — that is hideOutsideRoot (3.2). Or scope finds no folder for this page (3.1).
Nothing, but rootPath … is not a folder with visible pages	The folder does not exist, or everything in it is hidden (9.2).
A page is missing from the navigation	Draft, unlisted, navHide or an exclude pattern (2.3).
The order is wrong	2.2 – Sorting.
Folders and pages are called “index” or carry numbers	2.1 – Titles and folder pages.