Danny White 34454037d3 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 -->

2026-08-24 00:26:03 +00:00

667 B

Raw Permalink Blame History

View Raw