Menus, URLs and redirects

A new page that no menu points at is invisible, and a renamed docs URL breaks every external link to it. Both menus are hand-maintained JSON; nothing discovers pages automatically.

1. Preview menu — shared/data/menu.json

An object of top-level groups, each with nested children:

"base": {
  "title": "Interface",
  "icon": "package",
  "columns": 2,
  "children": {
    "badges": { "url": "badges.html", "title": "Badges", "badge": "New" }
  }
}

The pageMenu prop is the path of keys, dot-separated: base.badges matches the badges child of the base group. NavbarMenu.astro splits on . and highlights by key, so a mismatch between the page prop and the JSON key silently highlights nothing. menu-sample.json is a separate, smaller menu used by sample layouts — leave it alone unless the task is about those.

2. Docs menu — shared/data/docs.json

An array-based tree (menu) plus a links list for the external links in the docs header:

{ "title": "Getting started", "url": "/ui/getting-started",
  "children": [ { "title": "Installation", "url": "/ui/getting-started/installation" } ] }

• URLs are absolute paths without an extension and without a trailing slash (/ui/components/badge) — vercel.json sets trailingSlash: false, so a trailing slash costs a 308.
• The path mirrors the file: docs/content/ui/components/badge.mdx → /ui/components/badge; an index.mdx drops the last segment.
• A page in docs/content/** that is missing here still renders — it is simply unreachable by navigation, which is easy to miss because no build step complains.

3. Renamed or removed docs URLs

Add an entry to redirects in docs/lib/redirects.ts, next to the existing ones. That one table feeds docs/astro.config.mjs (real HTTP redirects), docs/middleware.ts (which must not rewrite these urls to .md) and the link gate, so it is the only place a redirect is written:

'/ui/base/markdown': { status: 301, destination: '/ui/base/prose' },

The plural component slugs kept there (alerts → alert, cards → card, …) are the pre-Astro URLs still present in Google's index and in external links — that is the standard this repo holds itself to: an old URL keeps working. The Vercel adapter turns these into real HTTP redirects; without an adapter they would only be meta-refresh pages.

Update in the same pass: shared/data/docs.json, any related: front matter pointing at the old path, and <DocsLink path="…"> on the matching preview page.

4. Verify with the link gate

pnpm run check:docs-links

It resolves, from source and without a build: markdown links and related: in docs/content/**/*.mdx, menu and link URLs in shared/data/docs.json, redirect sources and destinations from docs/lib/redirects.ts, href literals in docs components, <DocsLink path="…"> and getDocsUrl('…') in the demo site, plus asset paths that really render. Anchors are checked against real heading slugs.

It does not check menu.json: a wrong preview URL or a pageMenu key that matches nothing shows up only in the browser. Open the page and confirm the menu entry is highlighted (astro-dev skill).

5. Checklist

• New preview page added to menu.json with a .html url, and its pageMenu prop equals the dot-path of the keys
• New docs page added to docs.json at the right depth, url absolute and extension-free
• Renamed or removed docs URL has a 301 in docs/lib/redirects.ts
• related: entries and <DocsLink path="…"> updated to the new path
• pnpm run check:docs-links clean
• Menu highlighting checked in the browser