Navigation on Example Agency

Side navigation

Mon, 01 Jan 0001 00:00:00 +0000

Where it comes from

Nothing declares this menu. It is the content directory: every page under the top-level section, ordered by weight, nested exactly as the directories are. Add a folder with an _index.md and it appears.

The nav is rooted at the top of the tree rather than at the page’s parent. Rooted at the parent, this page would list only its two siblings, and the rest of the documentation would disappear the moment you opened a subsection.

Breadcrumb

Mon, 01 Jan 0001 00:00:00 +0000

The trail is built from the page’s ancestors, so it needs no configuration. The current page is a span carrying aria-current="page", never a link — a link to the page you are on is a dead end.

At the top level the breadcrumb renders nothing at all. A trail with one entry is noise.

Every trail also emits schema.org BreadcrumbList metadata, which costs nothing at render time and is what produces the trail shown under a search result. Turn it off with:

In-page navigation

Mon, 01 Jan 0001 00:00:00 +0000

Turning it on

It is front matter, not a shortcode:

in_page_nav: true
in_page_nav_headings: "h2"

A shortcode can only render inside main, and this component has to be a sibling of main for the two to lay out side by side. Front matter is the only place the decision can be made in time.

Choosing which headings

USWDS scans h2 and h3 by default, which sweeps up headings that belong to components — a summary box’s h3 shows up as if it were a section of the document. On a page using components, narrow it to h2.