Uh oh!
There was an error while loading. Please reload this page.
docs: derive section landing-page cards from the page tree + lint drift - #2567
Merged
Conversation
Section index card grids (e.g. foundations) were hand-written and drifted from the sidebar (meta.json) and the actual pages. Make them derive from the fumadocs page tree (single source of truth) and add CI lint so the card grid and navigation can't fall out of sync again. - resolveSectionChildren + <AutoCards/>, bound in both v4 and v5 docs routes (correct /docs vs /v5/docs URL spaces) - getLLMText expands <AutoCards/> so llms.txt/.md/copy-page keep child links - manualCards frontmatter opt-out for curated pages (source.config.ts) - checkSectionCards (card<->nav completeness) + checkMetaEntriesResolve (dangling meta entries) in scripts/lint.ts - convert foundations + errors (drift fixes) and v5 observability to AutoCards - mark deploying + ai as manualCards (intentionally curated) - remove dangling meta entries: v4 cancellation (x2), root introduction (x2), v4/internal serializable-abort-controller Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
|
Contributor
Uh oh!
There was an error while loading. Please reload this page.
pranaygp added a commit
that referenced
this pull request
Jun 23, 2026
…testing * origin/main: Trace /flow route initialization (#2592) Version Packages (beta) (#2591) feat(web): add trace step shortcut helper (#2582) [web-shared] reskin json viewer (no duplicates, better colours and navigation) (#2434) Send occurredAt with workflow events (#2580) docs: use actual eve logo and tidy OSS nav dropdown (#2586) Display occurredAt in trace details (#2581) fix(next): discover root entrypoints (#2564) [core] Turbo: skip the unused run_started event-log preload (#2569) fix(next): prewarm SWC plugin cache (#2538) [world-vercel] Use v3 stream endpoint (supports transparent reconnect on timeout) (#2424) [core] Retry stream reopen against the reconnect budget (#2334) Add Platformatic World to worlds-manifest.json (#1450) docs: derive section landing-page cards from the page tree + lint drift (#2567)
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Problem
Section landing pages (e.g.
foundations/index.mdx) render a<Cards>grid that's supposed to link to every page in that section. That grid was hand-written, so it drifted from the two other representations of the same list:meta.jsonpages— the sidebar nav.mdxfiles on disk<Cards>inindex.mdxConcrete drift this fixes:
v5/foundationswas missingcancellation;v5/errorswas missingabort-signal-timeout-in-workflow; and severalmeta.jsonentries pointed at pages that don't exist.Approach (single source of truth + lint)
Hybrid: derive cards from the fumadocs page tree where possible, and lint-enforce parity everywhere else.
resolveSectionChildren(tree, url)(lib/geistdocs/section-children.ts) — walks the page tree (built frommeta.json+ frontmatter) and returns a section's children in nav order. Handles both leaf pages and sub-folders (folder.index). This one function is the shared source of truth.<AutoCards />(components/geistdocs/auto-cards.tsx) — renders the card grid from those children. Bound per-route in both docs routes so hrefs land in the right URL space (/docs/...for v4,/v5/docs/...for v5).getLLMTextexpands<AutoCards/>into<Card>JSX in the markdown export, sollms.txt/.md/ copy-page keep the child links (a bare<AutoCards/>tag would otherwise strip them from agent-facing markdown).manualCards: truefrontmatter opt-out (source.config.ts) for pages whose grid is intentionally curated (links outside the section, custom layout, deliberate omissions).scripts/lint.ts(already CI-gated vialint.yml):checkSectionCards— every section index must use<AutoCards/>, setmanualCards: true, or have a<Card>for every nav child.checkMetaEntriesResolve— every plain-slugmeta.jsonentry must resolve to a real page/folder.Authoring model going forward
<AutoCards />(drift-proof; card text comes from each child's frontmattertitle/description).<Cards>+manualCards: true.Content changes
<AutoCards/>:foundationsanderrors(both had real drift), v5observability.manualCards: true:deploying(links/worlds, omits theworld/subfolder),ai(tutorial with a curated next-steps grid).cancellation(foundations + how-it-works), rootintroduction(v4 + v5 — vestigial;/docsredirects to/docs/getting-started), v4/internalserializable-abort-controller(v5-only page).Verification
bun ./scripts/lint.ts(the docs CI gate) passes; both new checks were confirmed to fail on injected drift (removed card / re-added dangling entry).cancellationin/v5/docs/...; errors lists all 15; markdown export expands<AutoCards/>to real card links.Docs Preview
Pages whose card grid changed (behind Vercel deployment protection — requires team access):
🤖 Generated with Claude Code