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.
 
-```
-<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
 
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 (
-    <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>
   )
 }
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 @@
-<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>
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"