mirror of
https://github.com/supabase/supabase.git
synced 2026-09-07 02:20:52 +08:00
320111b06b
Closes DOCS-1261 _WAVE plugin shows headers creating jumps in hierarchy. Preview on the left:_ <img width="1022" height="417" alt="Screenshot 2026-07-29 at 2 42 07 PM" src="https://github.com/user-attachments/assets/f5e3bd09-8dbf-45e3-8a7f-70d7334fd25b" /> <img width="408" height="663" alt="Screenshot 2026-07-29 at 2 44 33 PM" src="https://github.com/user-attachments/assets/6b952a81-40e5-4a9d-b08a-190c71575cac" /> ## Problem Four shared components in `apps/docs` render a hardcoded heading tag no matter where they're used: - `NamedCodeBlock` renders a code block's filename as an `<h6>` - `ProjectConfigVariables` renders a variable label as an `<h6>` - `StepHikeCompact.Details` renders a step title as an `<h3>` - `IconPanel` renders its title as an `<h5>` Since these are fixed, they often land in the wrong spot in a page's heading order (like an h6 right after an h2), which breaks navigation for screen reader users. This showed up in the [header hierarchy triage report](https://app.notion.com/p/supabase/Playwright-E2E-Triage-Reports-3ab5004b775f81e3bc60d058fa5a02c1) — fixing these 4 components alone resolves 72 of the 159 heading-order violations found. ## Solution Swapped the heading tag in each component for a `<span>` with the same classes. None of these are really "headings" for the content that follows, so they shouldn't be in the tag tree at all. The one wrinkle: this codebase applies heading font weight/family through a global CSS rule keyed off the tag name (h1-h6), not something the tag gives you for free. So each span now sets that styling explicitly, plus a margin to match what was there before. Nothing else changed — same classes, same layout. ## Manual testing Staging preview: https://docs-git-ui-header-hierarchy-supabase.vercel.app Check that each one still looks right: - [NamedCodeBlock](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/self-hosting/docker) — filenames above the code blocks - [ProjectConfigVariables](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/auth/quickstarts/react-native) — the "Project URL" / "Publishable key" labels (this page also has a `NamedCodeBlock` inside the numbered steps) - [StepHikeCompact](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/database/beekeeper-studio) — the step titles ("Create a new connection", etc.) - [IconPanel](https://docs-git-ui-header-hierarchy-supabase.vercel.app/docs/guides/resources) — the "Auth0" / "Firebase Auth" panel titles under "Migrate to Supabase" I also ran typecheck, lint, and the docs test suite locally — all green. <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Style** * Updated headings and labels across documentation and UI components for more consistent typography. * Improved spacing, font weight, and block-level layout for project variables, step details, code tabs, and icon panels. * Preserved existing text content and conditional display behavior. <!-- end of auto-generated comment: release notes by coderabbit.ai --> Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
Directives
Directives are a custom feature of the Supabase docs content system, which allows you to extend MDX to provide custom functionality.
Why not a React component?
MDX supports React components, and that is the preferred way to add new features. If your use case is supported by a React component alone, use that instead.
Custom directives are used to implement features that need low-level parse or compile-time control over the MDX AST.
Syntax
We reserve a special syntax for directives, which start with a $ sign. For example:
<$CodeSample />
This syntax was chosen because it is both:
- Sufficiently standard to be supported by MDX parsers without needing to build a custom extension.
- Sufficiently uncommon to avoid collisions with other React components used in docs.