Building and Editing a Menu

Menus are edited in the Design workspace: the Menus section for your site’s own navigation, and the Documentation section for the menus behind your documentation and API sets. Both use the same editor. Expand a menu in the list and its tree opens inline, with the menu’s controls appearing on its title row.

One thing to settle before you start. Nothing in a Leed menu stores a position number — no order field exists anywhere in the model. Position is where an item sits: a drag in the CMS, or a move or reorder operation over the API, MCP or the CLI. Everything below assumes it.

If you have not read what a menu is and why a documentation menu behaves unlike every other one, start at Menus and Navigation — this page is the controls.

The menu toolbar

Expanding a menu reveals a row of icon buttons beside its name. Which ones you get depends on the menu.

Creating a menu is not on this row. The ＋ at the top of the Menus panel makes one. The Documentation panel has no ＋ at all, because a documentation set’s left menu is created for you when you create the page type — there is nothing to make by hand.

Creating a menu

The ＋ opens a dialog titled New Menu with a single Name field; Enter submits. Menu names must be unique in your workspace — reusing one is refused.

Menu settings

The gear opens Menu Settings, which holds two things:

• Name — the rename, applied when you press Save.
• Expanded — “Menu is expanded by default on the site.” This one is not waiting for the Save button; toggling the checkbox writes immediately.

Deleting a menu

The trash opens a confirmation reading “Are you sure you want to delete “<name>”? This cannot be undone.” Deletion is a soft delete in the CMS — the record is retained and stops being listed — but it also commits a version of your site’s menu file without that menu’s key. That is the one operation that removes a key, and it is why deleting and recreating is the only clean way out of a bad menu name.

Building the tree

Hover any row and its controls appear on the right.

Two asymmetries in that table are enforced rather than cosmetic.

A documentation page item cannot own children. So on a docs menu, Add Folder and Add Page appear on folders only. This is not a UI preference — the server rejects a save that nests anything under a page item, with 400 "A docs page item cannot have children — place pages inside folders instead". On a site menu there is no such rule and every item gets the full set.

Delete appears only when the item has no children. Empty a folder before you remove it. This stops you deleting a subtree by accident, and it is the reason removing a section is a two-step job: move or delete the pages, then delete the folder.

Every page of a documentation set stays in its menu. On a docs menu the server refuses any change that would leave a page of the set out of the menu — removing its item, removing a folder together with its contents, or changing an item’s link — with a 409 naming the page: “… would disconnect ‘…’ from the docs menu: every page of a documentation set must stay in its menu.” The delete dialog says so up front. Move the page to another folder instead, or delete the page itself; an item whose page has already been deleted can be removed freely.

When an API set has Navigation Menu Locked switched on — the lock exists on API page types only — Add Folder and Add Page disappear from every row, and an amber padlock sits beside the menu’s name with the tooltip “Navigation menu locked — unlock in Settings → Page Types to reorder, move, or rename.” You can still change icons, tooltips and the disabled flag; anything that would move a URL is refused with a 403.

New items land in a specific place, which is worth knowing so you are not hunting for one you just made: an item added at the top level goes to the top of the list, and an item added inside a folder goes to the bottom of that folder.

Adding a page

Add Page opens a dialog titled Add Page with two routes.

Create new page opens the standard New Page dialog with the documentation set’s page type already filled in and locked, and hands the target folder to the server so the new page is filed inside it. This is the only way to create a page directly inside a folder — creating it anywhere else and moving it afterwards works, but takes an extra menu save. The option is hidden when the set has no bound page type, and when the page type is Content Locked, since a locked type refuses new pages.

Link existing page opens the link picker, the same one the editor uses for body links. Unpublished pages are included deliberately, so you can build a whole navigation ahead of a launch. The item’s visible name comes from the picker’s link text, falling back to Untitled if it is blank.

If the page you pick is already somewhere in this menu you get a Page already in menu dialog with Add anyway, Cancel, and a Don’t ask me again checkbox. On a site menu, adding the same page twice is legitimate — a footer that repeats a header link, for instance. On a documentation left menu it is not: the server will reject the save with a 409, because a documentation page may be referenced once, in exactly one docs menu, workspace-wide.

Renaming an item

Double-click a row’s label and it becomes an input. Enter commits, Escape cancels.

Here is the mechanic that catches everybody. Each item has two pieces of text:

• name — the label the published navigation renders.
• title — the hover tooltip, and nothing else.

The CMS tree displays the title when one is set, and only falls back to the name when it is empty. That is a sensible display rule and a quiet trap: change an item’s Tooltip and the tree shows the new text, while the published sidebar still shows the name.

Pages you add with Link existing page are not affected: their name comes from the picker’s link text, which is the page’s title as written.

The item settings dialog

The gear on a row opens Edit Menu Item, subtitled “Changes save automatically.” There is no Save button; typed fields save shortly after you stop typing, and everything else saves on the spot. Done closes it.

This dialog does not edit the item’s name. The name is the double-click rename on the row, and only that.

Icons

Icons live on the menu item. There is no page-level icon field anywhere in Leed, so a documentation page’s sidebar icon is a property of its menu entry, not of the page — which also means the same page linked from two site menus can carry two different icons.

Select Icon opens the Font Awesome picker and writes a class string such as fa-solid fa-book. Change Icon replaces it, Remove clears it, and once an icon is set a Color button appears beside it.

The Color control writes a Tailwind text-color class onto the item, which is what the CMS tree renders the glyph with. The published menu emits that same value as an inline style attribute rather than as a class, so a color chosen here is reliable as an editor aid and should not be treated as a site-facing styling control. Color your published navigation from your stylesheet instead.

Reading the row at a glance

The tree marks a few states inline, so you can audit a menu without opening anything:

Clicking a row’s label opens the page it points at, so the tree doubles as a way to move through a documentation set while you are editing it. Rows that do not point at a page — folders, external links — are not clickable in that way; double-click still renames them.

What publishing a menu commits

flowchart TD
  EDIT["You edit the tree<br/>drag, rename, add, delete"] --> SAVE["Each edit is written<br/>as one operation"]
  SAVE --> STALE{"Did someone else change<br/>the menu first?"}
  STALE -->|yes| CONFLICT["409 concurrent_update —<br/>re-read and try again"]
  STALE -->|no| GUARD{"Is this a documentation<br/>left menu?"}

  GUARD -->|no| DIRTY
  GUARD -->|yes| CHECKS["Server guards run:<br/>page item with children → 400<br/>page already placed → 409<br/>page would be disconnected → 409<br/>navigation locked → 403<br/>path collision → 409"]
  CHECKS -->|"any guard fails"| REJECT["The whole change is rejected —<br/>nothing changes"]
  CHECKS -->|"all pass"| MOVES["A new URL is staged for every page<br/>whose folder ancestry changed"]
  MOVES --> RIGHTS{"Do you hold<br/>publish rights?"}
  RIGHTS -->|yes| NOW["Moved pages are committed<br/>and deployed now"]
  RIGHTS -->|no| LATER["Each move lands on that page's<br/>next publication"]
  NOW --> DIRTY
  LATER --> DIRTY

  DIRTY["The menu is marked as having<br/>unpublished changes"] --> DEPLOY["You select it on the Deploy tab"]
  DEPLOY --> MERGE["Merged into the site's menu data<br/>under the menu's NAME"]
  MERGE --> BUILD["The site builds"]
  BUILD --> NAV["The navigation renders —<br/>items pointing at unpublished pages<br/>are dropped without a message"]

Three facts that diagram is compressing:

• Each changed menu is its own entry. It appears on the Deploy tab as Menu: … and publishes independently of every other menu. A menu you have not touched since its last publish is skipped even if you select it.
• The Deploy selection is the menu, not the pages it points at. Publishing a menu never publishes its targets, and an unpublished target is silently omitted from the rendered navigation rather than rendering as a dead link.
• The site file is merged by menu name and never pruned. Your menu is written in under its name; every other menu in the file is left exactly as it was.

That combination gives you the verification step: publish the pages first, then look at the navigation. Checking a nav before its targets are live tells you nothing, because the missing entries look identical to entries you forgot to add.

The Deploy tab, and how to publish a subset of what is pending, are covered in Publishing Changes. Moving a folder in a documentation menu has consequences well beyond the nav — what is staged, what is committed, and when — and those are on Folders Set Your URLs.

An MCP client edits this same tree one item at a time, never as a whole: add_menu_item, remove_menu_item, move_menu_item, reorder_menu_items and set_menu_item_fields for items, update_menu_fields for the menu’s own name and Expanded flag, and create_menu for a new draft menu. Each call carries the menu’s current revision, so a call made against a menu somebody else has just changed is refused with 409 concurrent_update rather than overwriting their work, and any write that would leave the same item id in the tree twice is refused with a 400 naming it. Publishing goes through publish_pending_changes. From the CLI the same operations are leed settings menu list|get|set|add|remove|move|reorder|set-menu. That, and the rest of the structural tooling, is in MCP Tools: Site Structure. Creating a page from Create new page opens the standard dialog described in Managing Pages.