Category navigation reference

The navigation is rendered by [category_nav] and injected automatically into archive templates that do not already contain it. This page documents the behavior an integration can rely on.

Contexts

The navigation resolves one of two contexts:

Outside those, it renders nothing.

Rendering modes

Two axes decide the markup:

Hierarchical or flat, from the per-menu-type setting. Wine lists default to flat; the other types default to nested.

Links or anchors. On a category archive the entries link to the sibling categories. On a menu archive, where all sections are on one page, the entries are anchors to the sections.

Anchor identifiers are derived from the taxonomy and term, so they are stable across renders of the same term.

Ordering

Terms are read with the stored position in the term meta key tax_position, ascending. Any custom navigation must reproduce that ordering to match the rest of the product.

Terms that are skipped

The navigation is deliberately quiet when there is nothing to navigate:

• terms with no posts, directly or in their descendants, are not rendered;
• a navigation that would contain a single term is not rendered at all.

Empty output from [category_nav] is normal, not an error.

The utility items

Up to three controls are appended after the category entries, each from a per-menu-type setting:

They are rendered as toggles pointing at the corresponding off-canvas panels, so a custom archive must provide those panels for the controls to be useful.

Colors

Three palette settings drive the navigation's appearance: the divider color, the text color used by links and the active indicator, and the background color used behind the bar and its side fades.

They resolve to palette slots rather than fixed values, so a custom stylesheet should read the same variables rather than hardcoding colors.

Attributes

[category_nav] accepts one attribute:

The flat/nested mode and the utility toggles are settings, not attributes, so that the same markup behaves consistently across every archive of a menu type.

Automatic injection

Archive markup passing through pom_archive_template_html receives the navigation when it does not already contain [category_nav]. To control placement precisely, include the shortcode in your markup and the injection will not apply.

Integration guidance

• Prefer the shortcode over building navigation from get_terms().
• If you must build your own, reproduce the tax_position ordering and the empty-term suppression.
• Provide the off-canvas panels the utility toggles expect.
• Do not assume a fixed number of entries; the bar is horizontally scrollable by design.