Navigation and links

CanAI keeps navigation as data: two menus (primary and footer) that templates loop over, and link helpers that follow the visitor's language and survive page moves.

What it is and when to use it

CanAI has exactly two menu locations, primary and footer. Header and footer templates never hold a list of links; they loop over the menu you maintain in WordPress (Appearance → Menus) or write over MCP. That way an owner can change the menu without touching a template, and the same menu is translated and given language prefixes for free.

You want Use
The header or footer links get_menu('primary') / get_menu('footer')
A link to an internal page by path turl('/contact/')
A link to a page by its slug slug_url('contact')
A link to a specific page, whatever its slug turl(id_url(42))

Menu item titles are translated (they are ordinary strings, see Multilingual) and menu URLs already carry the current language prefix. turl() returns any internal path as an absolute URL for the current language: no prefix on the default language, /ms/… on Malay. A URL on another host, mailto:, tel: or #anchor is returned unchanged. slug_url() is language-aware too. Never build a language prefix by hand.

Each menu item can also carry a description, a Lucide icon name and an image (a media ID). In Appearance → Menus these appear as extra fields on every item; templates read them from the item.

Example: a header that follows the menu

<header>
  <a href="{{ turl('/') }}">{{ t('Home') }}</a>
  <nav aria-label="Main">
    <ul>
      {% for item in get_menu('primary') %}
        <li>
          <a href="{{ item.url }}"{% if item.active %} aria-current="page"{% endif %}>{{ item.title }}</a>
          {% if item.children %}
            <ul>{% for sub in item.children %}<li><a href="{{ sub.url }}">{{ sub.title }}</a></li>{% endfor %}</ul>
          {% endif %}
        </li>
      {% endfor %}
    </ul>
  </nav>
</header>

Items carry title, url, target, classes, active and children. Do not render an item's children a second time at the top level, and do not add a hand-written fallback list for an empty menu.

Setting the menu up from an agent

Three abilities mirror Appearance → Menus. Locations are always primary or footer.

{ "location": "primary",
  "items": [
    { "title": "About", "page": "about", "icon": "info" },
    { "title": "Gallery", "page": "gallery", "children": [
      { "title": "Auditorium", "page": "gallery/auditorium" } ] },
    { "title": "Contact", "url": "/contact/" }
  ] }

A slug used by several pages is refused with ambiguous_page; pass the page path or ID instead.

Per-language menus

On a multilingual site each language either uses the default menu with its labels translated (the default), or a menu of its own. Choose per language and location under CanAI → Translations → Menus, where you can also start a language's own menu as a translated copy of the default. Over MCP, pass lang to write-menu or assign-menu; write-menu with copy_default: true and lang makes the copy, and assign-menu with menu_id: null goes back to the translated default.

Parent pages and page paths

Pages can sit under a parent (/gallery/auditorium/). Over MCP:

Moving a page changes its URL and its subpages' URLs, and WordPress keeps no redirect for pages. Menus, id_url() and bare-slug slug_url() links follow the page; a slug_url() call with a path and any hard-coded path do not. update-page warns when a published page's URL changes, and tells you to find the leftovers with wpcanai/grep-content and fix them with wpcanai/replace-in-meta. Export and import match pages by path, so a hierarchy survives a move between sites (see Export and import).

If something looks wrong

wpcanai/scan reports these navigation and link findings (see Scan and audit):

Finding Meaning and fix
hardcoded_nav A header or footer holds a hand-written list of links. Replace it with a get_menu() loop.
unknown_menu_location get_menu('x') names a location that is not primary or footer.
legacy_menu_location wpcanai_primary / wpcanai_footer still work, but rename them.
menu_not_assigned The template renders a location with no menu assigned. Run write-menu for it.
menu_fallback_chain One get_menu() falls back to another, or to hardcoded links in {% else %}. Keep one call.
menu_children_twice Sub-items are rendered again beside their parent.
hardcoded_lang_prefix A template builds /ms by hand. Use turl().
unlocalised_internal_href An internal href skips the current language. Wrap it in turl().
link_unresolved slug_url('x') matches no page, or several. It renders an empty href. Pass the path, or use turl(id_url(N)).
link_moved A literal path points where a page used to be. The message says where it is now.

Errors you may see from the menu and page abilities: invalid_location, invalid_lang, invalid_item, ambiguous_page, invalid_parent (parent missing, trashed or not a page) and parent_loop (the new parent is under the page you are moving). A link that renders as an empty href almost always means a slug_url() that matches nothing.

Related