fix(web/starlight): render top-level link-only sidebar entries as leaf links#2182
Merged
Conversation
Two openssh-server containers (ports 22022/22023) plus lifecycle helpers. Deterministic test keypair committed to the repo for reproducibility; no production value. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…f links
The sidebar loader unconditionally wrapped every top-level entry as
`{ label, collapsed, items }`, so any entry without an `items` array (or
with an empty one) rendered as a collapsible group header with no children
and discarded its `link`. Glossary hit this on the v4-0-0-snapshot sidebar:
`{"label": "Glossary", "link": "/v4-0-0-snapshot/glossary/"}` rendered as
an unclickable stub in the nav, even though the page built and was
reachable by URL.
Fix: when a top-level entry has a `link` and no children, pass it through
as `{ label, link }` so Starlight renders it as a leaf. Groups with
children continue to be wrapped as before.
Verified against a clean develop build: Glossary now renders
`<a href="/v4-0-0-snapshot/glossary/">` in the sidebar HTML.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
web/sites/guides/src/sidebars/*.jsonsupports three shapes for a top-level entry:{ label, link, items: [...] }{ label, link, items: [] }{ label, link }(noitemskey)The sidebar loader in
astro.config.mjs:48-52only handled shape 1 correctly. Shapes 2 and 3 rendered as empty<details><summary>group headers with no children and thelinkdiscarded — clicking them did nothing.On the live v4 guides nav today: Glossary (shape 3) renders as an unreachable stub, even though
/v4-0-0-snapshot/glossary/builds and is reachable by URL. Deployment & Operations, Contributing & Project, Upgrading were also affected on develop (shape 2) — #2181 fixes those by populating theiritemsarrays, but the root cause — the loader — is here.Fix
Detect link-only top-level entries in
buildSidebarForVersionand pass them through as{ label, link }so Starlight renders them as leaf links:```js
if (g.link && (!g.items || g.items.length === 0)) {
return { label: g.label, link: g.link };
}
```
Groups with children continue through the existing wrap-as-group path.
Verification
Built against a clean develop checkout. Before the fix, `grep 'Glossary' dist/v4-0-0-snapshot/index.html` shows it inside a `
` with no children and no link. After the fix:- `pnpm build` clean (330 pages, no warnings)
- Glossary sidebar entry now renders as a clickable `` link
- Other v4 groups with populated `items` still render as collapsible groups (regression check)
- v2-5-0 and v3-0-0 sidebars unchanged
- #2181 — Phase 2c guides rewrite. Merging this fix unblocks the Glossary nav entry on that PR. The other three groups (Deployment, Contributing, Upgrading) are populated by docs(docs): v4 guides phase 2c — ship deployment, contributing, upgrading, glossary #2181 and hit the wrap-as-group path regardless.
```html
Glossary
```
All three sidebar versions (v2-5-0, v3-0-0, v4-0-0-snapshot) continue to build; the fix only changes behavior for entries that were previously broken.
Test plan
Related
🤖 Generated with Claude Code