Deep dive: Menus: HubPeople Help

What this covers

There are two ways the toolkit builds your site's menus: native (hand-coded into your pages) and CMS dynamic (placeholders the portal fills in). This explains what each means, the trade-offs, and how to choose. It doubles as a reference an AI agent can act on.

New in v1.3.0. The toolkit no longer defaults to the CMS menu. It now asks which you want, with no default, before it builds the first page that needs a menu. Before v1.3.0 it defaulted to the CMS all-in-one nav and treated a hand-coded menu as something to avoid; now native menus are a first-class, supported option.

The choice, and how it is made

Before building the first page that needs a menu, Claude asks which menu style you want and explains the trade-offs. Your answer is logged to build-assets/0-the-brand/notes/decisions.md and reused for the whole site, both the primary nav and the footer, so you are not asked again per page.

Native (your own) menus

A native menu is real HTML written into every page: a hand-coded <nav> with a list of links, plus a matching footer <ul>. For example:

<nav class="site-nav">
  <ul class="nav-list">
    <li><a href="../pricing">Pricing</a></li>
    <li><a href="../articles">Articles</a></li>
    <li><a href="../safety">Safety</a></li>
  </ul>
</nav>

Every link is relative, has no .html extension and no trailing slash (Home is the one exception), and points to a page that exists. On first use, the toolkit adds a reusable mobile drawer (its CSS and a little JS) so the native nav is responsive. The footer is the same idea: a hand-coded <ul> of links in place of the footer menu placeholder.

Upside: it renders exactly as written and shows in your local preview, and it is fully yours to style.
Downside: the links are hardcoded on every page, so changing the menu means editing and re-uploading every page.

The site audit knows your choice, so it will not flag a native nav; it does check that every link resolves.

CMS dynamic menus

A dynamic menu is a placeholder the portal fills in at render time. There are three:

{{menu.navigation.default}} is the all-in-one primary nav: a mobile drawer, a hamburger, automatic overflow of extra items into a "More" menu past five items, submenus, and built-in login and join buttons. It ships its own styles and script, so you drop the placeholder in and the portal renders a complete nav.
{{menu.navigation}} is a bare primary nav (just a list of links, no drawer, script, or buttons). Use it when you want a fully custom header and will own the responsive behaviour yourself.
{{menu.footer}} is the footer menu; it switches to a responsive multi-column layout once you have eight or more links.

Upside: you change the menu once in the portal with no rebuild, and the all-in-one nav gives you responsive chrome for free.
Downside: a placeholder does not render in your local preview (you see the token, not the menu), and the token can confuse non-technical users.

One quirk with the all-in-one nav. Its styles load after global.css, so trying to override its CSS variables at the same specificity silently does nothing. Style the specific element (for example the drawer) rather than re-declaring the variable.

Native vs dynamic, side by side

	Native (hand-coded)	CMS dynamic (placeholder)
Editing	Edit and re-upload every page	Change once in the portal, no rebuild
Local preview	Renders as written	Shows the placeholder token, not the menu
Responsive chrome	The reusable drawer the toolkit adds	Built in (for the all-in-one nav)
Clarity	What you see is what you get	The placeholder can confuse some users

How to choose

Pick native if you want what-you-see-is-what-you-get, full control of the markup, and your menu rarely changes.
Pick CMS dynamic if you want to edit your menu in the portal without rebuilding, and you want the built-in responsive drawer.

The same either way

Your Join and Login buttons always use {{join.url}} and {{login.url}}, and your footer legal links always use the {{footerLinks.*Url}} placeholders, whichever menu style you choose. Those are not affected by the menu decision.

How Claude handles it

Claude asks you early with the pros and cons, records your choice in notes/decisions.md, and reuses it for every page and future session, so your nav and footer stay consistent.

Example. "I want to manage my menus in the portal." Claude would use CMS dynamic menus: {{menu.navigation.default}} for the primary nav and {{menu.footer}} for the footer, and note the choice so every new page matches.