SKILL.md

---
name: managing-navigation
description: Use when adding, renaming, moving, or deleting docs pages, groups, tabs, anchors, versions, languages, or products in the navigation tree through the Mintlify Admin MCP, or when restructuring the sidebar.
---

# Managing Navigation

## Overview

Navigation is a tree of typed nodes edited with dedicated node tools inside a checked-out session — never through `update_config` (which rejects the `navigation` key). Node types: `page`, `group`, `tab`, `anchor`, `version`, `language`, `product`. Parent/child compatibility is enforced (groups cannot contain tabs; pages have no children).

## Explore first

`list_nodes` filters the tree: `parentId: null` = root nodes, `recursive: true` = all descendants (pair with omitted/null `parentId` to dump the whole tree), `type` = single type or array, plus `language`/`version`/`tab` scope filters. Paginates via `cursor`/`nextCursor` (limit max 500). You need real `nodeId`s from here before any mutation.

**Finding a page's nodeId by path**: `list_nodes { type: 'page', recursive: true }` and match each node's `data.href` against the page path (the same path `search` results and `read` use). There is no direct path-lookup parameter.

## Quick reference

| Task | Tool |
|------|------|
| New page | `create_node { parentId, data: { type: 'page', path, content } }` (MDX validated) |
| New group/tab/version/… | `create_node` with that type's name-shaped `data` |
| Rename group, set page frontmatter, change icon | `update_node { nodeId, data }` — partial merge, `data.type` must match stored type |
| Reorder or reparent | `move_node { nodeId, parentId?, order? }` — at least one required; `order` is 0-based; `parentId: null` = root |
| Rename a page's URL path | `move_node` (path/`href` is immutable in `update_node`) |
| Remove node + subtree | `delete_node { nodeId }` — returns `deletedNodeIds` |
| Redirect after deletion | `update_config { op: 'add_redirect', redirect: { source, destination, permanent? } }` — point `destination` at the closest surviving replacement page |

## Page frontmatter lives here

`update_node` with `data.type: 'page'` is the correct tool for `title`, `sidebarTitle`, `description`, `icon`, `tag`, `canonical`, `og:*`, `keywords`, `noindex`, `hidden`, `deprecated` — the merged fields serialize back into the MDX `---` block on save. `edit_page` must not touch frontmatter.

## Common mistakes

- Deleting a published page without adding a redirect — breaks inbound links; pair `delete_node` with `add_redirect`.
- Trying to set `href`/`pageId` via `update_node` — rejected as immutable; use `move_node`.
- Moving nodes across version/tab/language/product boundaries unintentionally — allowed, but the response flags `crossedBoundary: true`; check it.
- Guessing `nodeId`s — always fetch them from `list_nodes` first.
- Forgetting `save` — nav edits stay on the session branch until published.