Status banner

A status banner marks a whole page as deprecated, experimental, or about an old version. It shows an icon and a visible label, so the meaning never depends on colour alone. When you give it a replacement, the banner links to the page that replaces this one.

The banner is a leaf directive, so it has no body and takes its text from its attributes.

Syntax

::status-banner{status=deprecated replacement="/guide/new-install/" version="0.2.0"}

Options

Name	Type	Default	What it does
status	deprecated, experimental, or old-version	none	The banner's kind, with its own icon, label, and colour. Any other value, or none, renders nothing.
replacement	site path or https URL	none	The page that replaces this one, linked after "Replaced by". Anything else is not shown as a link.
version	string	none	The version the status applies to, shown after "Since". Missing or blank shows nothing.
id	string	status-banner-<status>	The banner's id base. Only letters, digits, -, and _ are kept; a repeat on the same page gets a numeric suffix.

Spaces and underscores in status are read as hyphens, so old_version and Old Version both mean old-version.

Example

::status-banner{status=deprecated replacement="/components/page-status/" version="0.2.0"}

::status-banner{status=experimental}

::status-banner{status=old-version version="0.1.0"}

Notes

• The directive is block-level in Markdown: put it on its own line, with a blank line before and after.
• Use status banners at the top of the content. Each banner has the role note and an id: the first banner of a status keeps the plain id (status-banner-deprecated, and so on), while a repeat of the same status gets a numeric suffix (status-banner-deprecated-2, and so on) and names its own visible label.
• An explicit id replaces the status-derived base. It is reduced to letters, digits, -, and _, so it cannot inject markup, and an id already used on the page is numbered rather than duplicated.
• data-status and data-severity expose the banner's normalized status and its severity (critical, warning, or info) to scripts and styles. Neither is a claim about the page's trustworthiness.
• This component is written in the page content. For a banner above the title, driven by the status, since, and replaced_by front matter keys, use Page status.
• Remove the banner when the page is current again. A status banner left on a finished page is worse than no banner.