Navigation

Navigation is the set of menus that tie your site together — the header menu, the footer menu, and the documentation sidebar. Each menu is a list of links you control.

Menu locations

SpiderPublish has three named menu locations, and your theme renders each one where it belongs:

  • Header — the primary navigation at the top of every page.

  • Footer — links grouped at the bottom of the page.

  • Docs sidebar — navigation for your documentation section.

Menu items

A menu is an ordered list of items. Each item has:

  • a label (the visible text),

  • a URL (internal like /pricing, or an external link),

  • an optional icon,

  • an optional badge (for example "New" or "Beta"),

  • optional children — items can nest to create dropdowns or grouped columns.

Three kinds of menu item

Every item is one of three kinds. You pick the kind per item, and you can mix all three in the same menu.

  • Link — you type the label and the URL. This is the original behaviour and it is still the default. Nothing about your existing menus changed.

  • Folder — you point the item at a page folder instead of typing a URL. The menu then shows that folder's pages, and it keeps itself up to date as you add, remove, rename, or reorder pages inside the folder.

  • Whole site — the same idea applied to your entire page tree: the item is generated from your top-level folders and pages.

Folder and Whole site items take a depth (1 to 3) that controls how many levels of nesting the menu expands.

Why bind a menu to a folder

A hand-typed menu goes stale the moment someone adds a page. A bound item cannot: it is generated from your real page tree every time a visitor loads the page.

It is also safer. A bound menu only ever shows pages that are published. A draft page you are still writing is never listed, so there is no way to accidentally leak an unfinished page into your public navigation by forgetting to remove it from a menu.

Two more rules worth knowing:

  • Items appear in the same order you dragged them into in Content → Pages. The menu order and the folder order are the same order — there is nothing separate to maintain.

  • Folders themselves are never pages. A folder in the menu points at its landing page (see below), and if the folder has no published pages yet it renders as plain text with no link, never as a broken link.

Editing menus

Go to Content → Navigation and pick the location you want to edit (header, footer, or docs sidebar). Add items, set their labels and URLs, nest them where needed, and reorder them.

For a Folder item, choose Folder in the item's source picker, pick the folder, and set the depth. The Live Preview pane shows the menu the way visitors will see it — fully expanded — while the item you are editing keeps showing the binding. That is deliberate: you are editing the rule, not a frozen snapshot of today's pages.

Save, then deploy to push the change live.

A Folder item needs a folder selected. If you leave one unset, Save stays disabled until you fix it — a menu is saved as a whole, so one incomplete item would otherwise discard the rest of your edits.

With the CLI or an agent

  • CLI — spideriq content navigation get [location] prints a menu; spideriq content navigation set <location> --items <json> (or --file) writes one back. The output of get pipes straight back into set.

  • MCP / agents — content_get_navigation and content_update_navigation read and write a whole menu at once. When updating, you send the complete list of items for that location, not a single item — so fetch first, change, then write back.

An item becomes folder-bound by carrying a source object:

{
  "items": [
    { "label": "Pricing", "url": "/pricing" },
    { "label": "Handbook", "source": { "kind": "folder", "folder_id": "…", "depth": 2 } }
  ]
}

Agents: do not write the expansion back. The read returns bound items with their source and an empty children list — that is correct, not a bug. If you replace the source with the expanded pages you saw on the live site, the menu becomes a hand-typed snapshot and permanently stops tracking your page tree.

Tips

  • Keep the header short. Five to seven top-level items is plenty; push the rest into the footer or dropdowns.

  • Match labels to page titles. Consistency between your menu labels and your page headings helps visitors orient.

  • External links open safely. Mark external items as external so they are clearly outbound.

  • Bind the sections that grow. A docs area, a handbook, a resource library — anywhere you keep adding pages — is worth binding to a folder. Keep hand-typed links for the handful of fixed destinations like Pricing and Contact.

Next steps