From 34454037d31a817654e514f9748590989496cf0b Mon Sep 17 00:00:00 2001 From: Danny White <3104761+dnywh@users.noreply.github.com> Date: Mon, 24 Aug 2026 10:26:03 +1000 Subject: [PATCH] clean up docs admonition structure (#48669) ## What kind of change does this PR introduce? Docs update. Resolves DEPR-634. Stacked on #48664. The linter package and CI revision pins will be updated after [supa-mdx-lint#121](https://github.com/supabase-community/supa-mdx-lint/pull/121) merges and is released. ## What is the current behavior? Admonition body content can contain structural headings, which inherit prose spacing and produce awkward callout layouts. Standalone Docs actions are also rendered as ordinary body content in two places. | Before | | --- | | 70168 | | _Recent violation with Markdown header in `children`. Notice the big gap up top._ | ## What is the new behavior? - Documents that admonition titles belong in the `title` prop, standalone calls to action belong in `actions`, and document sections belong outside admonitions. - Configures heading-inside-admonition violations as errors for the forthcoming linter release. - Moves the UI-library and wrapper dashboard buttons into the existing `actions` slot without changing the shared component. Validated with the forthcoming linter across all 810 Docs sources, Docs type-checking, targeted ESLint and Prettier checks, and desktop/mobile rendering. ## Summary by CodeRabbit * **Documentation** * Clarified admonition guidelines for optional titles, headings, rich content, and standalone calls to action. * Improved guidance on when contextual links and interactive examples belong in admonition content. * **Style** * Updated documentation call-to-action buttons to use the designated actions area. * **Quality Improvements** * Added validation to prevent headings inside admonitions and maintain consistent formatting. * Updated documentation linting to apply the latest validation rules. --- .github/workflows/docs-lint-v2-scheduled.yml | 4 ++-- .github/workflows/docs-lint-v2.yml | 4 ++-- apps/docs/CONTRIBUTING.md | 14 +++++++++-- .../WrapperDashboardIntegration.tsx | 24 +++++++++++-------- apps/docs/content/_partials/uiLibCta.mdx | 10 ++++---- supa-mdx-lint.config.toml | 3 +++ 6 files changed, 38 insertions(+), 21 deletions(-) diff --git a/.github/workflows/docs-lint-v2-scheduled.yml b/.github/workflows/docs-lint-v2-scheduled.yml index 16ca6e7596d..c70f66cfb67 100644 --- a/.github/workflows/docs-lint-v2-scheduled.yml +++ b/.github/workflows/docs-lint-v2-scheduled.yml @@ -32,10 +32,10 @@ jobs: ~/.cargo/registry/index/ ~/.cargo/registry/cache/ ~/.cargo/git/db/ - key: 6b08233ff8bca855f6a38246b2a8049332219188 + key: da6838d8d6898f28ec9ab432353b2707db9df8f5 - name: install linter if: steps.cache-cargo.outputs.cache-hit != 'true' - run: cargo install --locked --git https://github.com/supabase-community/supa-mdx-lint --rev 6b08233ff8bca855f6a38246b2a8049332219188 + run: cargo install --locked --git https://github.com/supabase-community/supa-mdx-lint --rev da6838d8d6898f28ec9ab432353b2707db9df8f5 - name: run linter env: GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/.github/workflows/docs-lint-v2.yml b/.github/workflows/docs-lint-v2.yml index 6f78808236c..2b1fa438622 100644 --- a/.github/workflows/docs-lint-v2.yml +++ b/.github/workflows/docs-lint-v2.yml @@ -54,10 +54,10 @@ jobs: ~/.cargo/registry/index/ ~/.cargo/registry/cache/ ~/.cargo/git/db/ - key: 6b08233ff8bca855f6a38246b2a8049332219188 + key: da6838d8d6898f28ec9ab432353b2707db9df8f5 - name: install linter if: steps.filter.outputs.docs == 'true' && steps.cache-cargo.outputs.cache-hit != 'true' - run: cargo install --locked --git https://github.com/supabase-community/supa-mdx-lint --rev 6b08233ff8bca855f6a38246b2a8049332219188 + run: cargo install --locked --git https://github.com/supabase-community/supa-mdx-lint --rev da6838d8d6898f28ec9ab432353b2707db9df8f5 - name: install reviewdog if: steps.filter.outputs.docs == 'true' uses: reviewdog/action-setup@3f401fe1d58fe77e10d665ab713057375e39b887 # v1.3.0 diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.md index d7a0dfa8d21..67f870ed593 100644 --- a/apps/docs/CONTRIBUTING.md +++ b/apps/docs/CONTRIBUTING.md @@ -208,8 +208,18 @@ Choose the appropriate `type` for your admonition: - `caution`: Warn about behavior that could cause bugs, failed operations, unexpected results, or serious inconvenience but doesn't rise to the severity of `danger`. - `note`: Highlight an important prerequisite, constraint, clarification, or optional shortcut that doesn't represent a risk. If the information is essential to completing a step, include it in the procedure instead. -``` - +Structure an admonition with these props and content: + +- `title` (optional): Add a short callout title. Don't put Markdown or HTML headings inside an admonition. If the content needs a heading to structure the page, move the heading and its section outside the admonition. +- `children`: Add rich body content such as paragraphs, lists, links, and code. +- `actions` (optional): Add standalone calls to action so they remain separate from the body content. Keep contextual links and interactive examples in the body when they are part of the explanation. + +```mdx +Continue} +> Your content here diff --git a/apps/docs/components/WrapperDashboardIntegration.tsx b/apps/docs/components/WrapperDashboardIntegration.tsx index d48058c51b1..2a336c7c4e4 100644 --- a/apps/docs/components/WrapperDashboardIntegration.tsx +++ b/apps/docs/components/WrapperDashboardIntegration.tsx @@ -4,17 +4,21 @@ import { Admonition } from 'ui-patterns/Admonition' export function WrapperDashboardIntegration({ title, path }: { title: string; path: string }) { return ( - + + + Open wrapper in dashboard + + + } + >

You can enable the {title} wrapper right from the Supabase dashboard.

- - ) } diff --git a/apps/docs/content/_partials/uiLibCta.mdx b/apps/docs/content/_partials/uiLibCta.mdx index ba65465796b..20f3e79da90 100644 --- a/apps/docs/content/_partials/uiLibCta.mdx +++ b/apps/docs/content/_partials/uiLibCta.mdx @@ -1,9 +1,9 @@ - +Explore Components} +> UI components built on shadcn/ui that connect to Supabase via a single command. - - diff --git a/supa-mdx-lint.config.toml b/supa-mdx-lint.config.toml index 1e176d64176..0168a6eec30 100644 --- a/supa-mdx-lint.config.toml +++ b/supa-mdx-lint.config.toml @@ -27,3 +27,6 @@ rules.slang = "include('supa-mdx-lint/Rule004ExcludeWords/slang.toml')" [Rule006NoAbsoluteUrls] base_url = "https://supabase.com" + +[Rule007NoHeadingsInAdmonitions] +level = "error"