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,
including paths/index.md and paths/about.md. Create
paths/navigation/site.navigation.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:
[@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.
| 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.
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:
- [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.
These components work from the represented page:
<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 for its
responsive behavior.