Site navigation
Task#
Use this pattern when a reader needs to move between primary site areas, search the current site, choose a language, or choose a theme from any page. It is the persistent site header, not a local table of contents or a filter.
Composition#
The header composes Navigation, Search, Language toggle, and Theme toggle. The header partial owns their arrangement; the component pages own each unit’s API and behaviour.
Content and data#
Primary links come from the current language’s menu.main configuration. A menu entry may have one level of children. Search consumes the local Pagefind index produced after Hugo renders. The language toggle resolves a translated page when one exists and falls back to that language’s home or documentation root when it does not.
Responsive behaviour#
At and above 48rem, primary links appear in the header and a parent item can reveal one dropdown. Below that width, the brand and menu button remain visible; the opened panel contains primary navigation, search, language, and theme controls. The pattern does not hide any destination behind a hover-only interaction.
Implementation#
layouts/partials/header.html is the composition root. It renders the primary-nav landmark, search trigger, language links, and theme control together. layouts/_default/baseof.html renders the search dialog once so it can overlay the current page. assets/js/site.js manages mobile-menu, dropdown, search-dialog, and theme-preference behaviour; assets/css/site.css supplies the shared responsive layout and states.
Pattern manifest
- Kind
- Pattern
- Category
- Navigation
- Status
- Implemented
- Content and data
- menu.main configuration for each languagea translation or language-home fallback for every pagea locally generated Pagefind index for search
- Accessibility
- distinct landmarks for primary navigation and language selectionvisible focus and Escape behaviour for opened controlsmobile menu button state synchronized with its controlled panel
- Implementation
- Partial:
layouts/partials/header.htmllayouts/partials/search.htmllayouts/partials/theme-toggle.htmlLayout:layouts/_default/baseof.htmlCSS:assets/css/site.cssJavaScript:assets/js/site.jsConfiguration:config/_default/languages.ymlconfig/brand/languages.yml - Related patterns
- Documentation layout
Accessibility#
- The primary navigation and language switcher are separate named
<nav>landmarks. - The mobile menu uses a native button whose
aria-expandedstate and accessible label follow the controlled panel. - A parent desktop menu item remains a destination as well as a submenu trigger; keyboard focus and Escape expose and dismiss the submenu without trapping a reader.
- Search owns its modal focus management. Theme and language controls remain ordinary operable controls inside the opened mobile panel.
- Keep menu depth to one child level. A deeper tree is neither rendered nor navigable by this implementation.