feat: theme-owned navbars, navbarLinks option, and no footer (0.5.0)

[wardbryan3]

Summary

Implements decisions D1 to D4 of the docs theme sync record (https://claude.ai/code/artifact/5f4a93be-42aa-4c1f-9c53-d731ddbfb53e). The theme now renders the whole navbar itself and no site renders a footer.

• Two fixed navbar variants, chosen from baseUrl. Anything under /developer/ gets the developer navbar (brand mark linking to the developer overview, centred site title with the version badge, external buttons, colour-mode toggle). Everything else gets the public navbar (brand mark linking to the docs root, search, an empty Navbar/SiteActions slot for the main site's Ask AI button, colour-mode toggle). themeConfig.navbar is no longer read.
• One option: navbarLinks. At most two {label, url} entries, rendered as new-tab buttons on the developer navbar with the external-link icon and rel="noopener noreferrer" supplied by the theme. A third entry, an extra property, a relative or non-http url, or an unknown option fails the build with a message naming the problem.
• No footer. Footer returns null; the footer tokens and rules are gone from the design system CSS.
• Removed exports: navbarLogo, footerLogo, ThemeLogo. New exports: validateOptions, resolveNavbarVariant, LOGO_HREF, MAX_NAVBAR_LINKS, and the option types.
• Tests and CI. The validator has 14 node:test cases run against the compiled lib/; CI runs them and asserts lib/options.cjs ships in the tarball.
• Docs. README, usage, reference pages, and a Part 4 migration guide in both MIGRATION.md and the docs site. This repo's own docs site adopts the new contract (options passed, no navbar or footer config).

Why

The main docs site and the developer spokes had drifted on navigation, and per-spoke navbar config gave a new project every chance to skip the convention. Centralising both navbars in the theme, with a two-button surface as the only knob, removes that drift. Full rationale, including the rejected alternatives, is in the decision record.

Reviewer notes

• This is a breaking change and should ship as 0.5.0. Spokes drop themeConfig.navbar and footer and move their GitHub/registry links to the option; the migration guide's Part 4 walks through it.
• Assumptions to confirm: the public navbar keeps the lone version badge the main site shows today; logo hrefs are absolute URLs, matching the removed navbarLogo; the removed exports are removed outright rather than deprecated.
• Docusaurus quirk fixed during the build: when a plugin exports validateOptions, Docusaurus trusts the returned object to carry the plugin id. The validator defaults it to default; without that the build dies in path.join.
• Hamburger timing: with no themeConfig.navbar.items, Docusaurus hides the mobile toggle until the docs sidebar registers itself client-side, so it appears after hydration rather than in the static HTML. Upstream behaviour for any itemless navbar; documented on the components page.
• Window between merge and release: the docs job here builds against the newest 0.4.x from npm, so until 0.5.0 is released and just docs-pin 0.5.0 is run, this repo's docs spoke renders a bare navbar. Nothing breaks.
• Follow-ups in vantage-docs (not in this PR): upgrade to ^0.5.0, delete the main site's navbar/logo config and custom-askAI item type, add src/theme/Navbar/SiteActions/index.tsx rendering AskAIButton, and remove the Ctrl+I hint from AssistantLauncher.tsx (D5).

Test plan

• yarn build && yarn test: 14 passing
• Docs site built against the packed tarball (npm pack, npm install --no-save), typecheck and onBrokenLinks: 'throw' build both pass
• Developer build HTML: brand link to /developer/, centred title and version, GitHub and npm as target="_blank" with rel, no theme-layout-footer
• Public build HTML (temporary baseUrl: '/'): brand link to the docs root, no centred title, lone version badge, no external buttons, no footer
• Phone width: hamburger present; drawer lists GitHub and npm first, then the docs sidebar
• CI green on both jobs (Node 24; local verification ran on Node 22 with --ignore-engines)
• After merge: just release 0.5.0, then just docs-pin 0.5.0

🤖 Generated with Claude Code

[jamesbeedy]

+1