Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

fix(ui): align Admonition titles and docs link hover with prose (#48428)

Danny Whited1e7c403ac0c
diff --git a/apps/docs/content/guides/integrations/build-a-supabase-oauth-integration/oauth-scopes.mdx b/apps/docs/content/guides/integrations/build-a-supabase-oauth-integration/oauth-scopes.mdx
index d40563b3f4a..278ad08fb54 100644
--- a/apps/docs/content/guides/integrations/build-a-supabase-oauth-integration/oauth-scopes.mdx
+++ b/apps/docs/content/guides/integrations/build-a-supabase-oauth-integration/oauth-scopes.mdx
@@ -7,7 +7,7 @@ subtitle: 'Scopes let you specify the level of access your integration needs'
<Admonition type="note">
-Scopes are only available for OAuth apps. Check out [**our guide**](/docs/guides/integrations/build-a-supabase-oauth-integration) to learn how to build an OAuth app integration.
+Scopes are only available for OAuth apps. Check out [our guide](/docs/guides/integrations/build-a-supabase-oauth-integration) to learn how to build an OAuth app integration.
</Admonition>
diff --git a/apps/docs/content/guides/platform/multi-factor-authentication.mdx b/apps/docs/content/guides/platform/multi-factor-authentication.mdx
index b1ef06cc409..d460dcb6232 100644
--- a/apps/docs/content/guides/platform/multi-factor-authentication.mdx
+++ b/apps/docs/content/guides/platform/multi-factor-authentication.mdx
@@ -6,7 +6,7 @@ subtitle: 'Enable multi-factor authentication (MFA) to keep your account secure.
<Admonition type="note">
-This guide is for adding MFA to your Supabase user account. If you want to enable MFA for users in your Supabase project, refer to [**this guide**](/docs/guides/auth/auth-mfa) instead.
+This guide is for adding MFA to your Supabase user account. If you want to enable MFA for users in your Supabase project, refer to [this guide](/docs/guides/auth/auth-mfa) instead.
</Admonition>
diff --git a/apps/docs/features/docs/MdxAnchor.tsx b/apps/docs/features/docs/MdxAnchor.tsx
index 30b2b54db42..c792fab63ec 100644
--- a/apps/docs/features/docs/MdxAnchor.tsx
+++ b/apps/docs/features/docs/MdxAnchor.tsx
@@ -23,17 +23,50 @@ const flattenChildrenToText = (node: unknown): string => {
return ''
}
-export function MdxAnchor({ href, children, ...rest }: ComponentPropsWithoutRef<'a'>) {
+/** Same resting/hover contract as Studio InlineLink (no brand/green link color). */
+const mdxAnchorClassName =
+ 'underline transition underline-offset-2 decoration-inherit hover:decoration-foreground text-inherit hover:text-foreground'
+
+const relForTarget = (target?: string, rel?: string) => {
+ if (target !== '_blank') return rel
+ const tokens = new Set((rel ?? '').split(/\s+/).filter(Boolean))
+ tokens.add('noopener')
+ tokens.add('noreferrer')
+ return [...tokens].join(' ')
+}
+
+/**
+ * Docs MDX `<a>` mapper. Same resting/hover contract as Studio InlineLink:
+ * inherit text + decoration, then foreground on hover.
+ */
+export function MdxAnchor({
+ href,
+ children,
+ className,
+ target,
+ rel,
+ ...rest
+}: ComponentPropsWithoutRef<'a'>) {
+ const linkClassName = cn(mdxAnchorClassName, className)
+ const resolvedRel = relForTarget(target, rel)
+
if (!isExternalHref(href)) {
return (
- <a href={href} {...rest}>
+ <a href={href} target={target} rel={resolvedRel} className={linkClassName} {...rest}>
{children}
</a>
)
}
const label = flattenChildrenToText(children).trim()
return (
- <a href={href} aria-label={label ? `External Source: ${label}` : undefined} {...rest}>
+ <a
+ href={href}
+ target={target}
+ rel={resolvedRel}
+ aria-label={label ? `External Source: ${label}` : undefined}
+ className={linkClassName}
+ {...rest}
+ >
{children}
<ExternalLinkIcon
size={14}
diff --git a/packages/config/typography.config.js b/packages/config/typography.config.js
index 508f17766a5..8607488bbfd 100644
--- a/packages/config/typography.config.js
+++ b/packages/config/typography.config.js
@@ -130,13 +130,15 @@ module.exports = {
paddingBottom: '2px',
fontWeight: '400',
opacity: 1,
- color: 'var(--foreground-default)',
+ // Match Studio InlineLink: inherit body color, foreground on hover
+ color: 'inherit',
textDecorationLine: 'underline',
- textDecorationColor: 'var(--foreground-muted)',
+ textDecorationColor: 'inherit',
textDecorationThickness: '1px',
textUnderlineOffset: '2px',
},
'a:hover': {
+ color: 'var(--foreground-default)',
textDecorationColor: 'var(--foreground-default)',
},
figcaption: {
@@ -199,7 +201,7 @@ module.exports = {
'--tw-prose-body': 'var(--foreground-light)',
'--tw-prose-headings': 'var(--foreground-default)',
'--tw-prose-lead': 'var(--foreground-light)',
- '--tw-prose-links': 'hsl(var(--brand-500))',
+ '--tw-prose-links': 'inherit',
'--tw-prose-bold': 'var(--foreground-light)',
'--tw-prose-counters': 'var(--foreground-light)',
'--tw-prose-bullets': 'var(--foreground-muted)',
diff --git a/packages/ui-patterns/src/Admonition/Admonition.test.tsx b/packages/ui-patterns/src/Admonition/Admonition.test.tsx
index 0f0482fd0ef..a86b6e67339 100644
--- a/packages/ui-patterns/src/Admonition/Admonition.test.tsx
+++ b/packages/ui-patterns/src/Admonition/Admonition.test.tsx
@@ -119,7 +119,7 @@ describe('Admonition', () => {
expect(within(screen.getByRole('alert')).queryByText(`${name}:`)).not.toBeInTheDocument()
})
- it('renders the title as a paragraph with its own margin', () => {
+ it('renders the title via AlertTitle (paragraph, not a heading)', () => {
render(<Admonition type="note" title="Manual approval required" description="Body copy." />)
const note = screen.getByRole('alert', { name: 'Note' })
@@ -127,8 +127,8 @@ describe('Admonition', () => {
expect(note.querySelector('h1, h2, h3, h4, h5, h6')).not.toBeInTheDocument()
expect(title.tagName).toBe('P')
- expect(title).toHaveAttribute('data-admonition-title')
- expect(title).toHaveClass('mb-0.5')
+ expect(title).toHaveAttribute('data-slot', 'alert-title')
+ expect(title).toHaveClass('!mt-0', 'mb-0.5', 'font-medium')
})
it('wraps a string description in a paragraph', () => {
@@ -137,4 +137,19 @@ describe('Admonition', () => {
const note = screen.getByRole('alert', { name: 'Note' })
expect(within(note).getByText('Body copy.').tagName).toBe('P')
})
+
+ it('wraps MDX children in AlertDescription', () => {
+ render(
+ <Admonition type="note">
+ <p>Children body copy.</p>
+ </Admonition>
+ )
+
+ const note = screen.getByRole('alert', { name: 'Note' })
+ const paragraph = within(note).getByText('Children body copy.')
+
+ expect(paragraph.tagName).toBe('P')
+ expect(paragraph.parentElement).toHaveClass('text-sm')
+ expect(paragraph.parentElement).toHaveAttribute('data-slot', 'alert-description')
+ })
})
diff --git a/packages/ui-patterns/src/Admonition/Admonition.tsx b/packages/ui-patterns/src/Admonition/Admonition.tsx
index 530f65658b5..7333aac1d74 100644
--- a/packages/ui-patterns/src/Admonition/Admonition.tsx
+++ b/packages/ui-patterns/src/Admonition/Admonition.tsx
@@ -1,5 +1,5 @@
import { forwardRef } from 'react'
-import { Alert, AlertDescription, cn } from 'ui'
+import { Alert, AlertDescription, AlertTitle, cn } from 'ui'
import { TYPE_LABEL, TYPE_TO_VARIANT } from './Admonition.constants'
import type { AdmonitionLayout, AdmonitionProps, AdmonitionType } from './Admonition.types'
@@ -7,6 +7,9 @@ import { AdmonitionTypeIcon } from './AdmonitionIcons'
export type { AdmonitionLayout, AdmonitionProps, AdmonitionType }
+const admonitionBodyClassName =
+ '[&_p]:!mt-0 [&_p]:!mb-1.5 [&_p:last-child]:!mb-0 [&_ul]:!my-1.5 [&_ol]:!my-1.5 [&_li]:!my-0.5'
+
export const Admonition = forwardRef<
React.ComponentRef<typeof Alert>,
Omit<
@@ -66,28 +69,31 @@ export const Admonition = forwardRef<
]
)}
>
- <div
- {...childProps?.description}
- className={cn(
- 'text-foreground-light',
- // Exclude the title <p> so these MDX body resets don't override its mb-0.5
- // ([&_p]:!mb-1.5 beats !mb-0.5 on specificity: class+element vs class).
- '[&_p:not([data-admonition-title])]:!mt-0 [&_p:not([data-admonition-title])]:!mb-1.5 [&_p:not([data-admonition-title]):last-child]:!mb-0',
- '[&_ul]:!my-1.5 [&_ol]:!my-1.5 [&_li]:!my-0.5',
- childProps?.description?.className
- )}
- >
+ <div>
{title && (
- <p
+ <AlertTitle
{...childProps?.title}
- data-admonition-title
- className={cn('mb-0.5 font-medium text-foreground', childProps?.title?.className)}
+ className={cn('text-foreground', childProps?.title?.className)}
>
{title}
- </p>
+ </AlertTitle>
+ )}
+ {description && (
+ <AlertDescription
+ {...childProps?.description}
+ className={cn(admonitionBodyClassName, childProps?.description?.className)}
+ >
+ {description}
+ </AlertDescription>
+ )}
+ {children && (
+ <AlertDescription
+ {...childProps?.description}
+ className={cn(admonitionBodyClassName, childProps?.description?.className)}
+ >
+ {children}
+ </AlertDescription>
)}
- {description && <AlertDescription>{description}</AlertDescription>}
- {children}
</div>
{actions && (
<div
diff --git a/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.test.tsx b/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.test.tsx
index 83c0cb998c4..fa4e5022f99 100644
--- a/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.test.tsx
+++ b/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.test.tsx
@@ -60,6 +60,25 @@ describe('CustomHTMLElementsUtils', () => {
expect(result).toStrictEqual('function')
})
+
+ it('flattens nested element children including icons without props.children', () => {
+ const value = [
+ 'See ',
+ {
+ props: {
+ children: [
+ 'pg_prewarm',
+ // lucide icons (and similar) are objects without useful text children
+ { $$typeof: Symbol.for('react.element'), type: 'svg', props: undefined },
+ ],
+ },
+ },
+ ]
+
+ const result = getAnchor(value)
+
+ expect(result).toStrictEqual('see-pgprewarm')
+ })
})
describe('when value is a string', () => {
diff --git a/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.ts b/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.ts
index 244210c945a..082e2a1c7f6 100644
--- a/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.ts
+++ b/packages/ui/src/components/CustomHTMLElements/CustomHTMLElements.utils.ts
@@ -1,3 +1,20 @@
+/**
+ * Flatten React node trees to plain text for heading anchor ids.
+ * MDX headings often mix strings with inline nodes (`code`, links, icons);
+ * older code assumed every non-string had `props.children` and crashed when
+ * that was missing (e.g. lucide icons inside docs MDX links).
+ */
+const flattenNodeText = (node: unknown): string => {
+ if (node == null || typeof node === 'boolean') return ''
+ if (typeof node === 'string' || typeof node === 'number') return String(node)
+ if (Array.isArray(node)) return node.map(flattenNodeText).join('')
+ if (typeof node === 'object' && node !== null && 'props' in node) {
+ const props = (node as { props?: { children?: unknown } }).props
+ return flattenNodeText(props?.children)
+ }
+ return ''
+}
+
// Check if heading has custom anchor first, before forming the anchor based on the title
export const getAnchor = (text: any, { id }: { id?: string } = {}): string | undefined => {
if (id) {
@@ -15,27 +32,22 @@ export const getAnchor = (text: any, { id }: { id?: string } = {}): string | und
const formattedText = text
.map((x) => {
- if (typeof x !== 'string') {
- return x.props.children
+ if (typeof x === 'string') {
+ return x.trim()
}
-
- return x.trim()
+ return flattenNodeText(x)
})
.map((x) => {
if (typeof x !== 'string') {
return x
}
-
return slugify(x)
})
return formattedText.join('-').toLowerCase()
} else {
- const anchor = text.props.children
- if (typeof anchor === 'string') {
- return slugify(anchor)
- }
- return anchor
+ const flattened = flattenNodeText(text).trim()
+ return flattened ? slugify(flattened) : undefined
}
} else if (typeof text === 'string') {
if (hasCustomAnchor(text)) {
diff --git a/packages/ui/src/components/shadcn/ui/alert.tsx b/packages/ui/src/components/shadcn/ui/alert.tsx
index 56e00a1b8fc..e1590d9857e 100644
--- a/packages/ui/src/components/shadcn/ui/alert.tsx
+++ b/packages/ui/src/components/shadcn/ui/alert.tsx
@@ -31,40 +31,54 @@ const Alert = React.forwardRef<
HTMLDivElement,
React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
>(({ className, variant, ...props }, ref) => (
- <div ref={ref} role="alert" className={cn(alertVariants({ variant }), className)} {...props} />
+ <div
+ ref={ref}
+ data-slot="alert"
+ role="alert"
+ className={cn(alertVariants({ variant }), className)}
+ {...props}
+ />
))
Alert.displayName = 'Alert'
-const AlertTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(
- ({ className, ...props }, ref) => <h5 ref={ref} className={cn('mb-0.5', className)} {...props} />
-)
-AlertTitle.displayName = 'AlertTitle'
-
-const AlertDescription = React.forwardRef<
+const AlertTitle = React.forwardRef<
HTMLParagraphElement,
React.HTMLAttributes<HTMLParagraphElement>
->(({ className, children, ...props }, ref) => {
- // Automatically wrap primitive text nodes (string/number) in <p> tags for semantic HTML
- const content =
- typeof children === 'string' || typeof children === 'number' ? <p>{children}</p> : children
+>(({ className, ...props }, ref) => (
+ <p
+ ref={ref}
+ data-slot="alert-title"
+ className={cn('!mt-0 mb-0.5 font-medium', className)}
+ {...props}
+ />
+))
+AlertTitle.displayName = 'AlertTitle'
+
+const AlertDescription = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+ ({ className, children, ...props }, ref) => {
+ // Automatically wrap primitive text nodes (string/number) in <p> tags for semantic HTML
+ const content =
+ typeof children === 'string' || typeof children === 'number' ? <p>{children}</p> : children
- return (
- <div
- ref={ref}
- className={cn(
- 'text-sm text-foreground-light font-normal',
- // Optically align text in container
- 'mb-0.5',
- // Handle paragraphs
- '[&_p]:mb-0.5 [&_p:last-child]:mb-0',
- className
- )}
- {...props}
- >
- {content}
- </div>
- )
-})
+ return (
+ <div
+ ref={ref}
+ data-slot="alert-description"
+ className={cn(
+ 'text-sm text-foreground-light font-normal text-balance md:text-pretty',
+ // Optically align text in container
+ 'mb-0.5',
+ // Handle paragraphs (keep Studio density; shadcn uses mb-4)
+ '[&_p]:mb-0.5 [&_p:last-child]:mb-0',
+ className
+ )}
+ {...props}
+ >
+ {content}
+ </div>
+ )
+ }
+)
AlertDescription.displayName = 'AlertDescription'
export { Alert, AlertDescription, AlertTitle }