feat(docsite): on-this-page outline and linkable section headings#3101
Merged
Conversation
Adds a table of contents to documentation pages and makes section headings linkable, addressing the two doc-navigation requests. - Doc pages (guide, foundations, tokens, and package READMEs) render an "On this page" outline: a sticky aside on desktop and a sticky jump selector on mobile, with anchor offsets that clear the app header and the mobile selector. - Section headings get stable ids and a hover "copy link" affordance via a new AnchorHeading. Package/README headings also get ids + a TOC and now render at the same display-3 scale as the hand-authored docs. - Reworks Outline scroll-spy to track scroll position (stable, no indicator jitter; first item active at the top, last at the bottom) and delays the indicator on click until the smooth scroll settles. - Promotes the CLI README "Finding things" heading to a top-level section so it is no longer rendered as an orphan subsection. Co-authored-by: Cursor <cursoragent@cursor.com>
ernestt
requested review from
cixzhang,
ejhammond,
imdreamrunner,
josephfarina,
marie-lucas,
nynexman4464 and
thedjpetersen
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub. |
meta-cla
Bot
added
the
CLA Signed
This was referenced Jun 25, 2026
Contributor
PR Analysis Report📚 Storybook PreviewView Storybook for this PR 🧪 Sandbox PreviewView Sandbox for this PR No new or modified components detected. Bundle Size Summary
Accessibility AuditStatus: No accessibility violations detected. Generated by PR Enrichment workflow | Storybook | Sandbox | View full report |
Contributor
🚀 Vercel Preview Deployment
|
Co-authored-by: Cursor <cursoragent@cursor.com> # Conflicts: # apps/docsite/src/components/docs/DocPageLayout.tsx
josephfarina
approved these changes
Jun 25, 2026
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
2 participants
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
Adds a table of contents to documentation pages and makes section headings linkable.
Outlineaside on desktop and a sticky "jump to section"Selectoron mobile, with scroll-margin offsets that clear the app header (and, on mobile, the sticky selector).AnchorHeading: stableids plus a hover "copy link" affordance so any section can be deep-linked.ids + a TOC, render section headings at the samedisplay-3scale as the hand-authored docs, and the CLI README's "Finding things" heading is promoted to a top-level section (it was an orphan###before the first##).Outlinescroll-spy (core) to be scroll-position based — no indicator jitter, first item active at the top, last at the bottom — and the click indicator is deferred until the smooth scroll settles so it moves once instead of chasing the scroll.Issues
Closes #3077
Closes #3081
Test plan
pnpm -F @astryxdesign/docsite typecheckpnpm exec vitest run packages/core/src/Outline/Outline.test.tsxNotes
The core
Outlinescroll-spy/click changes could be split into a separate PR from the docsite integration if preferred — happy to do that.Made with Cursor