[@layout]: ../docs.layout.md

# Navigation

A `.navigation.md` Source defines a shared menu as a Markdown list. Import it
under a name and render it with `<x-navigation-nav />`.

Internal page links update the current document without a page-transition
animation in browsers that support enhanced navigation. Browser Back and Forward
keep their normal history and scroll behavior. This applies to live sites and
static publications; other browsers follow the links normally.

Browsers can reuse a previously fetched page after its host confirms freshness.
Static publications compare page hashes against their publication record. Eligible
live pages use the live connection to confirm their rendered response. Retention
is bounded, stays in the current tab, and does not provide offline storage.

Actions and live refreshes still read from the host. Standard production Auth
can reuse eligible pages privately; account changes invalidate retained pages across
tabs. Custom credential hosts without a session-generation contract, contextual Views,
and pages with unverified server render behavior use fresh reads. Input forms with per-render submission identifiers also use fresh reads.
If freshness confirmation fails, retained pages stop being reused while the
current page remains available during recovery.

Use the initialized files from [Quickstart](../start/first-site.guide.md),
including `paths/index.md` and `paths/about.md`. Create
`paths/navigation/site.navigation.md`:

```md
---
label: Workshop
---

- [Home](../index.md)
- [About](../about.md)
```

In the generated `paths/site.layout.md`, add the import and place the component
in the header, retaining its existing content outlet:

```md
[@nav.primary]: ./navigation/site.navigation.md

<x-navigation-nav name="primary" />
```

The import name and component's `name` must match. Link destinations resolve
relative to the navigation file; page routes and active states are generated.
Run `bun run dev` and open `/about.page`: the menu shows Home and About, with
About marked as the current page. Follow Home and confirm the active item changes.

---

## Menu contract

| Authoring | Meaning |
| --- | --- |
| `[@nav.primary]: ./site.navigation.md` | Registers this menu as `primary`. |
| `<x-navigation-nav name="primary" />` | Renders the registered menu. |
| `label` frontmatter | Accessible name for the navigation region. |
| Nested list items | Nested menu structure. |
| Relative `.md` link | Link to the Source's public page. |

Menus respect the current reader's access. The current page's link carries
`aria-current="page"`; active menu items also carry `data-pmx-active`.
Use these attributes to style navigation state.

The rendered lists use `.pmx-nav-list`, `.pmx-nav-item`, and `.pmx-nav-link`.
Control their spacing and orientation in your stylesheet.

---

## Nest a menu section

Create `paths/lessons/index.md` with `# Lessons` and
`paths/lessons/contrast.lesson.md` with `# Contrast` and a short explanation.
Append these entries to `paths/navigation/site.navigation.md`:

```md
- [Lessons](../lessons/index.md)
  - [Contrast](../lessons/contrast.lesson.md)
```

The menu now places Contrast inside Lessons. Follow Contrast and verify its
current-page marker; the structure comes from the nested Markdown list.

---

## Breadcrumbs and page outlines

These components work from the represented page:

```html
<x-breadcrumbs-trail />
<x-navigation-toc max-depth="3" />
```

Breadcrumbs follow the Source's folder hierarchy. Give a folder an `index.md`
page so readers can visit its overview. The table of contents follows headings
across the page's Blocks.

Use `min-depth`, `max-depth`, and `title` to configure the table of contents.
See [Components](../authoring/components.reference.md#table-of-contents) for its
responsive behavior.

## Related

- [Layouts](./layouts.reference.md) · [Links](../authoring/links.reference.md)
- [Build a workshop site](../start/build-a-site.guide.md)