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 |
| --- |
| <img width="1264" height="840" alt="70168"
src="https://github.com/user-attachments/assets/00aa7620-a6b4-452c-971f-b3ce2eda0e8c"
/> |
| _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.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## 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.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

.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 }}

.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

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.
 
-```
-<Admonition type="note" title="Optional title">
+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
+<Admonition
+  type="note"
+  title="Optional title"
+  actions={<Button>Continue</Button>}
+>
 
 Your content here
 

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 (
-    <Admonition type="note" className="mb-4">
+    <Admonition
+      type="note"
+      className="mb-4"
+      actions={
+        <Button asChild>
+          <Link
+            href={`https://supabase.com/dashboard/project/_/integrations/${path}/overview`}
+            className="no-underline"
+          >
+            Open wrapper in dashboard
+          </Link>
+        </Button>
+      }
+    >
       <p>You can enable the {title} wrapper right from the Supabase dashboard.</p>
-
-      <Button asChild>
-        <Link
-          href={`https://supabase.com/dashboard/project/_/integrations/${path}/overview`}
-          className="no-underline"
-        >
-          Open wrapper in dashboard
-        </Link>
-      </Button>
     </Admonition>
   )
 }

apps/docs/content/_partials/uiLibCta.mdx

@@ -1,9 +1,9 @@
-<Admonition type="note" title="Explore drop-in UI components for your Supabase app.">
+<Admonition
+  type="note"
+  title="Explore drop-in UI components for your Supabase app."
+  actions={<Button variant="primary" asChild><a href="https://supabase.com/library">Explore Components</a></Button>}
+>
 
 UI components built on shadcn/ui that connect to Supabase via a single command.
 
-<Button variant="primary" asChild>
-  <a href="https://supabase.com/library">Explore Components</a>
-</Button>
-
 </Admonition>

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"