feat(docs): improve TOC headings

[maxktz]

Summary

• expose installation step titles as TOC headings
• add hidden TOC test page
• add custom docs TOC with path-style active tracking

Testing

• pnpm -F web lint
• pnpm -F web typecheck

Summary by CodeRabbit

• New Features

  • Introduced a custom table of contents component with visual tracking of the currently active section as users scroll.

• Documentation

  • Refactored installation guide layout for improved clarity and readability.
  • Added comprehensive testing documentation page with extensive examples and best practices.

• Styling

  • Enhanced step component visual presentation.
  • Added new theme variables for improved design system consistency across light and dark modes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
paykit	Ready	Preview, Comment	Jun 6, 2026 7:35am

[coderabbitai]

Wondering what really moved? Review this PR in Change Stack to inspect semantic changes, definitions, and references.

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: d09a8fca-67d0-47a4-8ee8-c190800b1df8

📥 Commits

Reviewing files that changed from the base of the PR and between a961954 and 5b40e2f.

📒 Files selected for processing (6)

• apps/web/content/docs/installation.mdx
• apps/web/content/docs/test.mdx
• apps/web/src/components/docs/docs-page.tsx
• apps/web/src/components/docs/docs-toc.tsx
• apps/web/src/components/docs/mdx-text.tsx
• apps/web/src/styles/globals.css

---

📝 Walkthrough

Walkthrough

This PR implements a custom client-side table-of-contents component with SVG-based active section tracking, replacing the library TOC in the docs layout. It includes new styling tokens, enhanced step component styling, and refactored installation documentation alongside a test page for TOC edge cases.

Changes

Custom TOC with Active Path Tracking

Layer / File(s)	Summary
Core DocsToc component with SVG path computation apps/web/src/components/docs/docs-toc.tsx	DocsToc renders a sticky sidebar with TOC items; DocsTocItems measures link positions and computes an SVG polyline path using ResizeObserver; DocsTocTrack updates CSS variables (--track-top, --track-bottom) to clip the active segment; DocsTocItem renders individual links with depth-based padding.
DocsPage integration and component swap apps/web/src/components/docs/docs-page.tsx	Imports are updated to remove fumadocs-ui TOC and add local DocsToc; new DocsTocLayout helper renders DocsToc with width and footer props; TOC rendering conditional now uses DocsTocLayout.
CSS theme tokens and Steps component refinement apps/web/src/components/docs/mdx-text.tsx, apps/web/src/styles/globals.css	New --path CSS variable added to :root and .dark with oklch(...) values; @theme inline exposes --color-path alias; Steps component styling expanded with cn(...) for descendant h3 elements and not-first spacing.
Installation and test documentation apps/web/content/docs/installation.mdx, apps/web/content/docs/test.mdx	Installation guide refactored to use new step heading patterns and move database guidance inline; new test.mdx page with heading levels and edge cases to exercise TOC behavior.

🎯 3 (Moderate) | ⏱️ ~25 minutes

🐰 A sidebar with tracks so fine,
SVG paths that brightly shine,
Active sections marked with care,
Custom TOC beyond compare! ✨

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/docs-toc-headings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}