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.
wpcanai/get-menusreads each location's menu and item tree, every menu, and per-language translation counts.wpcanai/write-menusets a location's items. Each item has atitleplus apage(post ID, slug or path) or aurl; an item with children may have neither (a heading). Optionaldescription,attr_title,target,classes,icon(a Lucide name) andimage(attachment ID). Children nest three levels.merge: trueupdates items by title and appends;items: []empties the menu.wpcanai/assign-menuassigns an existing menu to a location (menu_id: nullclears it).
{ "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:
wpcanai/create-pageacceptsparentandmenu_order, and returnspathandurl.wpcanai/update-pagechanges a page'stitle,slug,status,parentormenu_orderwithout touching its body, on any page, Twig or blocks. The response includesprevious, the values to send to undo it.wpcanai/list-pagesreturns each page's slug, status, path and URL. Passall_pages: trueto include pages that were not made with CanAI and drafts.
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
- Multilingual: translated menu labels, language prefixes and the language switcher.
- Authoring Twig: the template functions in full.
- Templates and layouts: where header and footer templates live.
- Scan and audit: running
wpcanai/scan. - Export and import: page paths in bundles.
- MCP and agents: connecting an agent.