mirror of https://github.com/theNewDynamic/gohugo-theme-ananke.git

Patrick Kollitsch
7 hours ago df07ae28ed2b0ba31d1705239192229d94cda9fe
refs
author Patrick Kollitsch <83281+davidsneighbour@users.noreply.github.com>
Friday, November 20, 2026 11:32 +0100
committer Patrick Kollitsch <davidsneighbourdev+gh@gmail.com>
Friday, November 20, 2026 11:51 +0100
commitdf07ae28ed2b0ba31d1705239192229d94cda9fe
tree 3056fd182474bf13048595eed87bd919a2ccccf1 tree | zip | gz
parent 8c18c8412c9edc79d24e982c43a3ef58867a44af view | diff
feat(header): integrate configurable header and navigation (#1121)

The header now supports configurable components and nested navigation without requiring a replacement header template. This replaces #1119 and documents the deprecation tracked in #1120. Companion documentation: gohugo-ananke/documentation#76.

## Header layout and hooks

* Configure navigation groups and the ordered content components through `ananke.header`, with page and cascade overrides.
* Render logo, languages, menu, social links, title, and description through `hooks/header/<name>.html`. Custom names provide additional components, such as search.
* Add markup through component before/after hooks. Hook context includes the page, region, featured image, content variant, and navigation classes where applicable.
* Give navigation groups explicit lead, panel, and slot roles. Keep the logo and hamburger accessible below 60em.
* Provide stable navigation and submenu class hooks, including group styling. Resolve each configured class through page > cascade > site > theme default.

## Navigation behaviour

* Render child entries of the main menu, current-page and ancestor state, and accessible disclosure controls.
* Support `split` (default parent link plus arrow), `hover` (hover disclosure plus parent link), `click` (parent disclosure with its destination first as Overview or explicit linkTitle), and `toplevel` (first level only).
* Resolve submenu mode globally, through page/cascade settings, or per call to the reusable `navigation/menu.html` partial. Multiple menu instances receive unique IDs.
* Below 60em, use one hamburger panel with all included child levels expanded and indented. Parents remain links where possible; there are no individual submenu toggles or hover interactions.
* Support keyboard disclosure, Escape, outside-click dismissal, and focus recovery when crossing the responsive breakpoint.
* Keep links and child lists available without JavaScript. Add translated menu-button labels and submenu/overview labels.

## Compatibility and migration

Existing overrides of `site-header.html`, `page-header.html`, and `site-navigation.html` still render, but emit identifiable deprecation warnings. These extension points are scheduled for removal in v3 (#1120). Strict `--panicOnWarning` builds must migrate or temporarily suppress the specific warning IDs.

Existing child menu entries become visible; `toplevel` preserves first-level-only output. Custom CSS that depends on the old element structure needs review. Sites overriding `site-scripts.html` must include the new navigation script to enable disclosure controls. Missing configured component partials produce warnings.

The CLI logging helper supports deprecation severity and warning IDs. Compatibility checks cover override detection, warning deduplication, and suppression.

## Documentation and release workflow

* Explain the new configuration, hooks, class priority, responsive behaviour, and migration in the companion PR.
* Document that a published stable theme release must precede production documentation publication; merging into main alone is insufficient.
* User guides use the final production documentation paths: [header guide](https://ananke-documentation.netlify.app/customisation/header/), [menus](https://ananke-documentation.netlify.app/configuration/menus/), and [publication order](https://ananke-documentation.netlify.app/help/development/#release-and-publication-order).

## Validation

* Chromium browser suite: 94 passed, covering header groups, modes, multiple instances, keyboard/focus handling, mobile navigation, images, and no-JavaScript behaviour. Existing contrast cases remain marked as expected.
* Quickstart build and generated-HTML checks passed, including legacy override warnings and suppression.
* Theme fixture builds passed with Hugo 0.160.0, 0.161.1, and 0.170.1.
* Focused TypeScript and commit-hook checks passed. The inherited feature coverage catalogue issue for the edit-page shortcode remains outside this change.
* GitHub Hugo quickstart check passed.

## Integration

Squash into `development`, then merge documentation #76. The existing development squash has the same tree as this branch; complete this PR without introducing merge commits or losing changes. Publication to main and a stable release are separate steps.
changed files