1.3 – What happens at build time

From entry to component

Quartz reads quartz.config.yaml and creates a component for every active entry — in the place its layout block names, or without a block on the left with priority: 10. The plugin receives the options exactly as they are written in the file and fills in everything missing from its own defaults. A value it does not know — variant: vertikal, say — is replaced by the default and reported once (9.2).

Two entries with identical options share one component in Quartz. That is harmless as long as they sit in different places — except for element IDs, see 7.3.

From folder to tree

Quartz hands every component the list of all pages of the build. The tree is made from it:

1. Every page becomes a node. Its path (docs/setup) decides which folder it hangs in.
2. Every folder becomes a node whose link is the folder page — docs/index.
3. Hidden things drop out: tag pages, the 404 page, drafts, unlisted, navHide, exclude (2.3).
4. Every node gets a title (2.1).
5. The children of every folder are sorted (2.2).
6. Empty folders drop out.

Folders can always be linked. Without an index.md, Quartz’s folder-page plugin creates the folder page itself. It is in the same list and is treated like a real one — only its title comes from the directory name.

One tree per build, not per navigation

The tree is computed once and then read by all navigations that share the tree-shaping options: sorting, hiding, include/exclude, icons. Three entries that differ only in variant, scope or depth cost one tree, not three. On a multilingual site it is one tree per language (8.3).

One consequence is worth knowing: two navigations can place the same page differently if they sort or hide differently. That is intended — a pager by date next to a sidebar in manual order is a legitimate setup.

From tree and page to <nav>

For each page the navigation picks its part of the tree (chapter 3), marks the current page with active and every folder above it with active-trail, and writes finished HTML with relative links. Nothing is rebuilt in the browser. Switch JavaScript off and you get the same navigation.

What the browser adds

One script — one for all navigations of the site — adds what HTML alone cannot do:

What	Where it is needed
Remember open folders	persistState (5.1)
Open menus on hover, close them on Escape and on a click elsewhere	dropdown, mega, flyout (5.2)
Redirect panels that would stick out of the window or a column	the same three
Hold the page still behind the mobile menu, Escape	mobile: offcanvas (6.1)
Navigate when an option is chosen in the jump menu	select, mobile: select

Stylesheet and script reach the site once, however many navigations are on it.