docs-site/satteri-github-alerts

Sätteri mdast plugin that turns GitHub alerts (> [!NOTE] …) into Starlight asides.

Functions

Function Description

satteriGitHubAlerts Sätteri mdast plugin that turns GitHub alerts into Starlight asides. The guides keep GitHub’s > [!TYPE] syntax because it also renders on GitHub, where most people read the repository. The site used to rely on starlight-github-alerts for the conversion, and on Starlight 0.42 that plugin silently does nothing: it registers itself in front of an mdast plugin NAMED starlight-asides, while Starlight now registers its asides as an unnamed factory, so the lookup misses and the plugin returns without a word. Every alert then rendered as a plain blockquote opening with the literal [!WARNING]. This plugin does the same conversion from the site’s own mdastPlugins, which run before every plugin Starlight appends: it replaces the blockquote with a containerDirective named after the aside variant, exactly what :::caution parses to, and Starlight’s own asides plugin then renders it.

Function	Description
satteriGitHubAlerts	Sätteri mdast plugin that turns GitHub alerts into Starlight asides. The guides keep GitHub’s `> [!TYPE]` syntax because it also renders on GitHub, where most people read the repository. The site used to rely on `starlight-github-alerts` for the conversion, and on Starlight `0.42` that plugin silently does nothing: it registers itself in front of an mdast plugin NAMED `starlight-asides`, while Starlight now registers its asides as an unnamed factory, so the lookup misses and the plugin returns without a word. Every alert then rendered as a plain blockquote opening with the literal `[!WARNING]`. This plugin does the same conversion from the site’s own `mdastPlugins`, which run before every plugin Starlight appends: it replaces the blockquote with a `containerDirective` named after the aside variant, exactly what `:::caution` parses to, and Starlight’s own asides plugin then renders it.

Variables

Variable	Description
GITHUB_ALERT_ASIDE_VARIANTS	The Starlight aside variant each GitHub alert type renders as. Starlight has four variants for GitHub’s five types, so `IMPORTANT` and `WARNING` share `caution`, and `CAUTION` - GitHub’s most severe - takes `danger`. This is the mapping `starlight-github-alerts` uses.