@heroiclands/package-build 22.26.0 → 22.27.0

package/docs/reference/note-types.md

@@ -115,7 +115,6 @@ These fields are accepted by every note type. A field's value can still be irrel
 | `data.governance.ranks`   | list                   | The ladder of ranks the body confers — level, title, description.                               |
 | `data.governance.offices` | as authored            | Named offices, each with a description and optional dated holders.                              |
 | `data.seat`               | an Address             | Where the affiliation's authority sits.                                                         |
-| `data.domains`            | list of Addresses      | Places over which it holds sway.                                                                |
 | `data.population`         | number                 | How many people it counts.                                                                      |
 | `data.economy`            | list of Addresses      | What its economic life runs on — currencies, banking bodies, goods.                             |
 | `data.lore`               | list of Addresses      | Lore concerning it — the peoples it draws on, the god a faith venerates, its law, its calendar. |
@@ -128,7 +127,6 @@ These fields are accepted by every note type. A field's value can still be irrel
 | ---------------- | ------ | ------------------ |
 | `subType`        | sohl   | `system.subType`   |
 | `data.seat`      | sohl   | `system.seat`      |
-| `data.domains`   | sohl   | `system.domain`    |
 | `data.parents`   | sohl   | `system.parents`   |
 | `data.relations` | sohl   | `system.relations` |
 
@@ -463,33 +461,33 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
 
 **Subtypes:** `world`, `region`, `settlement`, `site`, `structure`, `feature`, `celestial`.
 
-| Field                                  | Shape                                                             | Meaning                                                                                                                             |
-| -------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `data.calendar`                        | an Address                                                        | Calendar used to display this place's dates.                                                                                        |
-| `data.demonym`                         | string                                                            | What a person from this place is called — a Vylarian.                                                                               |
-| `data.purpose`                         | string                                                            | The reason this settlement, site, or structure exists, selected from its placeCharacter tags.                                       |
-| `data.lore`                            | list of Addresses                                                 | Lore concerning this place — its peoples, its law, its calendar, its history.                                                       |
-| `data.parents`                         | list of Addresses                                                 | Enclosing places this one sits within.                                                                                              |
-| `data.population`                      | number                                                            | Approximate population, to two significant digits.                                                                                  |
-| `data.government`                      | an affiliation Address or null                                    | The governing affiliation; explicit null means complete anarchy. A positive population with no government key produces an advisory. |
-| `data.market`                          | number                                                            | What trade the settlement supports, on a scale of six: 1 hamlet, 2 village, 3 town, 4 market town, 5 city, 6 great city.            |
-| `data.borders`                         | list of `{ to, bearing }` entries                                 | Places sharing a frontier with this one — each the other's shortcode and where it lies from here.                                   |
-| `data.routes`                          | list of `{ to, bearing, mode, days, terrain?, leagues? }` entries | Journeys from this place's centre — where the destination lies, how it is travelled, and about how many days it takes.              |
-| `data.world.equatorialCircumferenceKm` | number                                                            | The distance round the body at its equator, in kilometres.                                                                          |
-| `data.world.surfaceGravityG`           | number                                                            | Surface gravity, as a multiple of Earth's.                                                                                          |
-| `data.world.axialTiltDegrees`          | number                                                            | The tilt of the axis, in degrees — what makes the body have seasons.                                                                |
-| `data.year.days`                       | number                                                            | How many days the body's year holds. Every calendar's months sum to it.                                                             |
-| `data.year.hoursPerDay`                | number                                                            | How many hours the day divides into.                                                                                                |
-| `data.year.minutesPerHour`             | number                                                            | How many minutes the hour divides into.                                                                                             |
-| `data.year.secondsPerMinute`           | number                                                            | How many seconds the minute divides into.                                                                                           |
-| `data.present`                         | a date                                                            | The day the setting stops and play begins — what an age is computed against.                                                        |
-| `data.body.diameterKm`                 | number                                                            | The body's diameter, in kilometres.                                                                                                 |
-| `data.body.orbitalRadiusKm`            | number                                                            | How far the body orbits from the one it circles, in kilometres.                                                                     |
-| `data.body.orbit`                      | string                                                            | The orbit's shape — `circular` means the cycle never varies.                                                                        |
-| `data.body.inclined`                   | boolean                                                           | Whether the orbit is inclined to the plane the world orbits in.                                                                     |
-| `data.moon.cycle`                      | number                                                            | How many days the body takes to return to the same phase.                                                                           |
-| `data.moon.newOn`                      | a day-precision date                                              | A day the body was new, written in the reference calendar.                                                                          |
-| `data.moon.eclipses`                   | string                                                            | How often the body eclipses or is eclipsed — `never`, `rare`, `occasional` or `frequent`.                                           |
+| Field                                  | Shape                                                             | Meaning                                                                                                                                                                             |
+| -------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data.calendar`                        | an Address                                                        | Calendar used to display this place's dates.                                                                                                                                        |
+| `data.demonym`                         | string                                                            | What a person from this place is called — a Vylarian.                                                                                                                               |
+| `data.purpose`                         | string                                                            | The reason this settlement, site, or structure exists, selected from its placeCharacter tags.                                                                                       |
+| `data.lore`                            | list of Addresses                                                 | Lore concerning this place — its peoples, its law, its calendar, its history.                                                                                                       |
+| `data.parents`                         | list of Addresses                                                 | Enclosing places this one sits within.                                                                                                                                              |
+| `data.population`                      | number                                                            | Approximate population, to two significant digits.                                                                                                                                  |
+| `data.government`                      | an Address or null                                                | The governing affiliation Address; the default target type is affiliation. Explicit null means complete anarchy. A positive population with no government key produces an advisory. |
+| `data.market`                          | number                                                            | What trade the settlement supports, on a scale of six: 1 hamlet, 2 village, 3 town, 4 market town, 5 city, 6 great city.                                                            |
+| `data.borders`                         | list of `{ to, bearing }` entries                                 | Places sharing a frontier with this one — each the other's shortcode and where it lies from here.                                                                                   |
+| `data.routes`                          | list of `{ to, bearing, mode, days, terrain?, leagues? }` entries | Journeys from this place's centre — where the destination lies, how it is travelled, and about how many days it takes.                                                              |
+| `data.world.equatorialCircumferenceKm` | number                                                            | The distance round the body at its equator, in kilometres.                                                                                                                          |
+| `data.world.surfaceGravityG`           | number                                                            | Surface gravity, as a multiple of Earth's.                                                                                                                                          |
+| `data.world.axialTiltDegrees`          | number                                                            | The tilt of the axis, in degrees — what makes the body have seasons.                                                                                                                |
+| `data.year.days`                       | number                                                            | How many days the body's year holds. Every calendar's months sum to it.                                                                                                             |
+| `data.year.hoursPerDay`                | number                                                            | How many hours the day divides into.                                                                                                                                                |
+| `data.year.minutesPerHour`             | number                                                            | How many minutes the hour divides into.                                                                                                                                             |
+| `data.year.secondsPerMinute`           | number                                                            | How many seconds the minute divides into.                                                                                                                                           |
+| `data.present`                         | a date                                                            | The day the setting stops and play begins — what an age is computed against.                                                                                                        |
+| `data.body.diameterKm`                 | number                                                            | The body's diameter, in kilometres.                                                                                                                                                 |
+| `data.body.orbitalRadiusKm`            | number                                                            | How far the body orbits from the one it circles, in kilometres.                                                                                                                     |
+| `data.body.orbit`                      | string                                                            | The orbit's shape — `circular` means the cycle never varies.                                                                                                                        |
+| `data.body.inclined`                   | boolean                                                           | Whether the orbit is inclined to the plane the world orbits in.                                                                                                                     |
+| `data.moon.cycle`                      | number                                                            | How many days the body takes to return to the same phase.                                                                                                                           |
+| `data.moon.newOn`                      | a day-precision date                                              | A day the body was new, written in the reference calendar.                                                                                                                          |
+| `data.moon.eclipses`                   | string                                                            | How often the body eclipses or is eclipsed — `never`, `rare`, `occasional` or `frequent`.                                                                                           |
 
 ### scenario
 

package/docs/reference/theme-pages.md

@@ -9,12 +9,12 @@ subType: reference
 
 `package-build site` writes a page's front matter; the shared Hugo theme reads
 it and draws the page around it. This reference describes that second half —
-the infobox rail, the hero band, the holdings and related cards, the place
+the infobox rail, the hero band, the government and related cards, the place
 map, search, and the markup an image or a figure renders as — and names the
 classes a consumer styles against.
 
 **None of the sections below is an authoring instruction.** `infoboxes`,
-`related`, `contains`, `held_by`, `holdings`, `map`, `package`, `slug`, `url`
+`related`, `contains`, `governed_by`, `governed_places`, `map`, `package`, `slug`, `url`
 and `title` cannot be written by a note at all: a note's top-level region is
 closed and does not admit them, so each arrives already resolved by the time
 the theme sees it. Read this page when a panel is missing or a class needs
@@ -166,7 +166,7 @@ artwork where the considered answer was "none". See
 declines one; the spelling differs from the hand-authored page's, and the two
 are not interchangeable.
 
-## The holdings card
+## The containment and government card
 
 `partials/holdings.html` renders a bordered card below the body and above the
 Related card, holding up to three small tables. The build derives this front
@@ -176,13 +176,13 @@ note and dropped if one carries them:
 ```yaml
 ---
 contains: [{ title: …, url: …, type: place, subType: … }] # places within this one
-held_by: [{ title: …, url: …, type: affiliation, subType: … }] # affiliations holding this place
-holdings: [{ title: …, url: …, type: place, subType: … }] # places this affiliation holds
+governed_by: [{ title: …, url: …, type: affiliation, subType: … }] # the governing affiliation of this place
+governed_places: [{ title: …, url: …, type: place, subType: … }] # places explicitly governed by this affiliation
 ---
 ```
 
-A place page carries `contains` and/or `held_by`; an affiliation page carries
-`holdings`. Each key is tested for independently — a page carrying none of the
+A place page carries `contains` and/or `governed_by`; an affiliation page carries
+`governed_places`. Each key is tested for independently — a page carrying none of the
 three renders no card, and a page carrying one renders one table.
 
 **`url` is absent for an entry with no page of its own** — a stub note with an
@@ -191,29 +191,29 @@ an entry's title renders as plain text; every other entry renders as a link.
 `partials/holdings/entry.html` carries the guard, the same one
 `partials/infobox/entry.html` already applies to its own `{text, url}` shape.
 
-**Within** (`contains`) and **Holdings** (`holdings`) list places, and each is
+**Within** (`contains`) and **Governed places** (`governed_places`) list places, and each is
 broken into groups by `subType`, in the closed order region, settlement, site,
 structure, feature — a `subType` outside that order, or missing entirely,
-groups last, alphabetically by its rendered label. **Held by** (`held_by`)
+groups last, alphabetically by its rendered label. **Governed by** (`governed_by`)
 lists affiliations, whose kinds have no fixed hierarchy to group by, so it
 stays one flat grid with the kind printed beside each name.
 
 Every grid is `repeat(auto-fill, minmax(14em, 1fr))`, the one the Related card
 uses, so a region with forty settlements stays scannable.
 
-| class                   | drawn as                                                             |
-| ----------------------- | -------------------------------------------------------------------- |
-| `.holdings`             | the card                                                             |
-| `.holdings-table`       | one of the three tables, label and body together                     |
-| `.holdings-table-label` | "Within" / "Held by" / "Holdings"                                    |
-| `.holdings-table-grid`  | the grid of entries (Held by; the innermost grid of Within/Holdings) |
-| `.holdings-kind-group`  | one kind's block within Within or Holdings                           |
-| `.holdings-kind-label`  | the kind label heading a group                                       |
-| `.holdings-entry-name`  | an entry's title, linked or plain                                    |
-| `.holdings-entry-kind`  | the kind printed beside a Held by entry                              |
+| class                   | drawn as                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------- |
+| `.holdings`             | the card                                                                        |
+| `.holdings-table`       | one of the three tables, label and body together                                |
+| `.holdings-table-label` | "Within" / "Governed by" / "Governed places"                                    |
+| `.holdings-table-grid`  | the grid of entries (Governed by; the innermost grid of Within/Governed places) |
+| `.holdings-kind-group`  | one kind's block within Within or Governed places                               |
+| `.holdings-kind-label`  | the kind label heading a group                                                  |
+| `.holdings-entry-name`  | an entry's title, linked or plain                                               |
+| `.holdings-entry-kind`  | the kind printed beside a Governed by entry                                     |
 
-A page whose front matter declares none of `contains`, `held_by` or
-`holdings` renders no card at all.
+A page whose front matter declares none of `contains`, `governed_by` or
+`governed_places` renders no card at all.
 
 ## The place map
 
@@ -291,9 +291,8 @@ for how an author writes `size`, `float` and a role.
 
 ## A numbered figure
 
-A `:::figure` fence wraps a picture, a table, a listing, a map or a passage of
-prose in a numbered, referable block. The content build decides which from
-the fence's contents, counts each kind separately, and emits the block with
+A leading caption wraps the next supported item in a referable block; `:@` also numbers it. The content build decides which from
+the next item, counts each kind separately, and emits the block with
 its label beneath whatever it holds:
 
 ```html
@@ -303,15 +302,14 @@ its label beneath whatever it holds:
 </div>
 ```
 
-The kind is `code`, `table`, `figure`, `map`, `poem` or `prose`, labelled **Code**,
-**Table**, **Figure**, **Map**, **Poem** and **Prose**. Every kind is drawn alike — the
+The kind is `code`, `table`, `figure`, `map`, `poem`, `prose` or `example`, labelled **Code**,
+**Table**, **Figure**, **Map**, **Poem**, **Prose** and **Example**. Every kind is drawn alike — the
 block carries the spacing, its contents add none of their own at the edges,
 and the label reads as a caption rather than as another paragraph of the body
-— so a kind added to the vocabulary arrives styled. A fence carrying an `id`
+— so a kind added to the vocabulary arrives styled. A caption carrying an `id`
 is a cross-reference target and takes the same scroll offset a heading does.
 
-`border` is the one class an author may write on a fence, and it draws the
-block as a boxed aside.
+Caption classes are unrestricted. The built-in `border` class draws the block as a boxed aside. Unnumbered captions use the same wrapper and show caption text without a numbered label.
 
 | class                    | drawn as                                   |
 | ------------------------ | ------------------------------------------ |
@@ -496,3 +494,7 @@ Each section below has its own landing page.
 ```
 
 A row is a linked title and, when the page carries one, its description.
+
+## Alerts
+
+The content renderer emits an `aside` with `alert` and `alert-note`, `alert-tip`, `alert-important`, `alert-warning` classes. The `alert-title` header contains a Font Awesome icon and the type's label. Shared styles supply a colored left rule, colored header and ordinary readable body; alerts do not use `details` and never start collapsed. Authored identifiers, additional classes and named attributes belong to the entire aside. Secret blocks retain their separate expandable presentation on the website.

package/engine/anchors.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * The anchors a note declares on headings and figure fences.
+ * The anchors a note declares on headings, captions, divs, poems and spans.
  *
  * **A leaf, deliberately.** This is asked by the link checker, by the content
  * index, and by the builds that emit a link, and they cannot all import one
@@ -29,15 +29,20 @@
  * @module
  */
 
+import { scanAlerts } from "./content-alerts.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+import { scanPoetry } from "./content-poetry.mjs";
+import { scanSpans } from "./content-spans.mjs";
+import { codeRegions } from "./code-fences.mjs";
+import { slugify } from "./content-slug.mjs";
 import { scanFigures } from "./content-figures.mjs";
 import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
 
 /**
- * The `{#slug}` and `:::figure {#slug}` anchors a note declares.
+ * The identifiers a note declares on headings, captions, divs, poems and spans.
  *
- * A bare `#` heading starts a journal page without declaring a slug, and so
- * does a figure fence that declares no id. A fence that declares one declares a
- * slug and starts an addressable journal page.
+ * Headings and captions may start journal pages. Div, poem and inline-span
+ * anchors address locations within their containing pages.
  *
  * @param {string} body - The note's markdown body, frontmatter already removed.
  * @param {number} [bodyLine] - The 1-based file line the body starts on, from
@@ -52,17 +57,15 @@ import { HEADING_LINE, splitHeadingAttributes } from "./heading-attributes.mjs";
  */
 export function collectAnchors(body, bodyLine = 1, resolveRole) {
     const anchors = [];
-    let inCodeBlock = false;
+    const literal = codeRegions(body, { spans: false, poetryAsProse: false });
+    let offset = 0;
     const lines = String(body ?? "").split("\n");
 
     for (let i = 0; i < lines.length; i++) {
-        // A fenced block's contents are not headings, and `#` is a comment in
-        // most of what gets fenced.
-        if (lines[i].trim().startsWith("```")) {
-            inCodeBlock = !inCodeBlock;
+        const lineOffset = offset;
+        offset += lines[i].length + 1;
+        if (literal.some((region) => lineOffset >= region.start && lineOffset < region.end))
             continue;
-        }
-        if (inCodeBlock) continue;
 
         const heading = HEADING_LINE.exec(lines[i]);
         if (!heading) continue;
@@ -79,10 +82,79 @@ export function collectAnchors(body, bodyLine = 1, resolveRole) {
         if (!figure.id) continue;
         anchors.push({
             slug: figure.id,
-            name: figure.label,
+            name: figure.label || figure.caption,
             level: 1,
             line: bodyLine + figure.line - 1,
         });
     }
+    const blockAnchors = (source, firstLine) => {
+        const sourceLines = source.split("\n");
+        for (const block of scanBlocks(source).blocks) {
+            if (block.id)
+                anchors.push({
+                    slug: slugify(block.id),
+                    name: block.title || block.id,
+                    level: 0,
+                    line: firstLine + block.start,
+                });
+            blockAnchors(
+                sourceLines.slice(block.start + 1, block.end).join("\n"),
+                firstLine + block.start + 1,
+            );
+        }
+    };
+    blockAnchors(String(body ?? ""), bodyLine);
+    for (const alert of scanAlerts(body).blocks) {
+        if (alert.id)
+            anchors.push({
+                slug: slugify(alert.id),
+                name: alert.title,
+                level: 0,
+                line: bodyLine + alert.start,
+            });
+    }
+    for (const poem of scanPoetry(body).blocks) {
+        if (poem.id)
+            anchors.push({
+                slug: slugify(poem.id),
+                name: poem.id,
+                level: 0,
+                line: bodyLine + poem.start,
+            });
+    }
+    for (const span of scanSpans(body).spans) {
+        if (span.id)
+            anchors.push({
+                slug: slugify(span.id),
+                name: span.text,
+                level: 0,
+                line: bodyLine + span.line - 1,
+            });
+    }
     return anchors.sort((a, b) => a.line - b.line);
 }
+
+/** Collisions involving a div, verse or inline-span anchor.
+ * Heading and caption collisions are diagnosed by their existing scanners.
+ * @param {string} body - Authored Markdown.
+ * @returns {Array<{line: number, column: number, message: string}>} Located collisions.
+ */
+export function markupAnchorFindings(body) {
+    const groups = new Map();
+    for (const anchor of collectAnchors(body)) {
+        const slug = slugify(anchor.slug);
+        if (!groups.has(slug)) groups.set(slug, []);
+        groups.get(slug).push(anchor);
+    }
+    const errors = [];
+    for (const [slug, anchors] of groups) {
+        if (anchors.length < 2 || !anchors.some((anchor) => anchor.level === 0)) continue;
+        for (const anchor of anchors.slice(1))
+            errors.push({
+                line: anchor.line,
+                column: 1,
+                message: `duplicate markup anchor "${slug}"`,
+            });
+    }
+    return errors;
+}

package/engine/art-fields.mjs

@@ -247,7 +247,7 @@ export function resolveArtRecord(index, value, defaultType, accepts) {
  * carries once an embed's address has been rewritten into the ordinary image
  * every surface renders ({@link module:engine/content-embeds.resolveEmbeds}).
  *
- * This is the lookup a `:::figure` fence's `map` counter reaches through —
+ * This is the lookup a captioned item's `map` counter reaches through —
  * see {@link module:engine/content-figures.scanFigures}'s `resolveRole` —
  * for a caller that reads a body after that rewrite: a Foundry journal, an
  * item or actor's documentation, and the book.

package/engine/base-compiler.mjs

@@ -61,7 +61,10 @@
  * @module
  */
 
+import { scanAlerts } from "./content-alerts.mjs";
 import { authoredFrontmatter } from "./index-records.mjs";
+import { markupAnchorFindings } from "./anchors.mjs";
+import { scanSpans } from "./content-spans.mjs";
 import { scanBlocks } from "./content-blocks.mjs";
 import { scanHeadingAttributes, withheldSections } from "./heading-attributes.mjs";
 import { scanFigures } from "./content-figures.mjs";
@@ -682,7 +685,12 @@ export class BasePackCompiler {
         // it made — `errors` or `findings`, never just the first — so nothing
         // here re-scans; it only stops taking `[0]`.
         const findings = [];
-        for (const secretError of scanBlocks(body).errors) {
+        for (const secretError of [
+            ...scanBlocks(body).errors,
+            ...scanAlerts(body).errors,
+            ...scanSpans(body).errors,
+            ...markupAnchorFindings(body),
+        ]) {
             findings.push({
                 message: secretError.message,
                 line: (this.currentNote?.bodyLine ?? 1) + secretError.line - 1,

package/engine/bundles.mjs

@@ -314,7 +314,7 @@ export class Bundles extends BasePackCompiler {
 
         // The markdown this pass reads has already had its embeds rewritten
         // into ordinary images, each `src` the pathname `pathnameRoles` keys
-        // its roles by — so a `:::figure` of a map names itself `Map 1` here
+        // its roles by — so a captioned map names itself `Map 1` here
         // exactly as the website and the book name the same picture.
         const roles = pathnameRoles(this.linkIndex);
 

package/engine/code-fences.mjs

@@ -104,10 +104,11 @@ function column(space) {
  * @param {object} [options]
  * @param {boolean} [options.spans=true] - Include inline code spans. Set false
  *   to consider only block-level code.
+ * @param {boolean} [options.poetryAsProse=true] - Treat verse bodies as inline prose.
  * @returns {Array<{start: number, end: number}>} Non-overlapping regions, in
  *   source order. `end` is exclusive.
  */
-export function codeRegions(markdown, { spans = true } = {}) {
+export function codeRegions(markdown, { spans = true, poetryAsProse = true } = {}) {
     const src = String(markdown ?? "");
     if (!src) return [];
     const lines = src.split("\n");
@@ -144,7 +145,10 @@ export function codeRegions(markdown, { spans = true } = {}) {
             let close = i + 1;
             while (close < lines.length && !closer.test(lines[close])) close++;
             // An unclosed fence runs to the end of the document.
-            regions.push(through(i, Math.min(close, lines.length - 1)));
+            if (poetryAsProse && /^poetry(?:\s|$)/.test(fence[3])) {
+                regions.push(through(i, i));
+                if (close < lines.length) regions.push(through(close, close));
+            } else regions.push(through(i, Math.min(close, lines.length - 1)));
             i = close;
             afterBlank = false;
             continue;

package/engine/content-alerts.mjs

@@ -0,0 +1,195 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+import MarkdownIt from "markdown-it";
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+import { slugify } from "./content-slug.mjs";
+
+const icon = (body) =>
+    `<svg class="alert-icon" viewBox="0 0 16 16" aria-hidden="true" fill="currentColor">${body}</svg>`;
+/** Alert titles and static icons shared by all publishing surfaces. */
+export const ALERT_TYPES = Object.freeze({
+    note: {
+        title: "Note",
+        icon: '<i class="alert-icon fa-regular fa-message" aria-hidden="true"></i>',
+        svg: icon(
+            '<path d="M2 1h12a1 1 0 0 1 1 1v9a1 1 0 0 1-1 1H6l-4 3V2a1 1 0 0 1 0-1Zm1.5 1.5V12l2-1.5h8V2.5Z"/>',
+        ),
+    },
+    tip: {
+        title: "Tip",
+        icon: '<i class="alert-icon fa-regular fa-lightbulb" aria-hidden="true"></i>',
+        svg: icon(
+            '<path d="M8 0a5 5 0 0 0-3 9v2h6V9a5 5 0 0 0-3-9Zm0 1.5A3.5 3.5 0 0 1 10 8l-.5.4v1.1h-3V8.4L6 8a3.5 3.5 0 0 1 2-6.5ZM5 12h6v1.5H5zm1 2.5h4V16H6z"/>',
+        ),
+    },
+    important: {
+        title: "Important",
+        icon: '<i class="alert-icon fa-solid fa-circle-info" aria-hidden="true"></i>',
+        svg: icon(
+            '<path d="M8 1a7 7 0 1 0 0 14A7 7 0 0 0 8 1Zm0 1.5a5.5 5.5 0 1 1 0 11 5.5 5.5 0 0 1 0-11Z"/><circle cx="8" cy="5" r="1"/><path d="M7.25 7h1.5v5h-1.5z"/>',
+        ),
+    },
+    warning: {
+        title: "Warning",
+        icon: '<i class="alert-icon fa-solid fa-triangle-exclamation" aria-hidden="true"></i>',
+        svg: icon(
+            '<path d="M8 0 0 15h16L8 0Zm0 3 5.5 10.5h-11L8 3Z"/><path d="M7.25 6h1.5v4h-1.5z"/><circle cx="8" cy="12" r="1"/>',
+        ),
+    },
+});
+const parser = new MarkdownIt();
+const titleParser = new MarkdownIt({ html: false });
+const marker = /^ {0,3}>[ \t]?\[!([^\]\n]+)\](.*)$/;
+/** Read alerts outside code examples, retaining inclusive source line ranges.
+ * @param {string} source - Authored Markdown.
+ */
+export function scanAlerts(source) {
+    const text = String(source ?? ""),
+        lines = text.split("\n"),
+        blocks = [],
+        errors = [];
+    let depth = 0;
+    for (const token of parser.parse(text, {})) {
+        if (token.type === "blockquote_close") {
+            depth--;
+            continue;
+        }
+        if (token.type !== "blockquote_open" || !token.map) continue;
+        depth++;
+        const [start, after] = token.map;
+        let first = lines[start] ?? "";
+        for (let level = 1; level < depth; level++) first = first.replace(/^ {0,3}>[ \t]?/, "");
+        const match = marker.exec(first);
+        if (!match) {
+            if (/^ {0,3}>[ \t]?\[!/.test(first))
+                errors.push({
+                    line: start + 1,
+                    column: lines[start].indexOf("[") + 1,
+                    message: "alert marker needs [!TYPE] brackets",
+                });
+            continue;
+        }
+        const at = { line: start + 1, column: lines[start].indexOf("[") + 1 };
+        const type = match[1].toLowerCase();
+        if (match[1] !== match[1].toUpperCase() || !Object.hasOwn(ALERT_TYPES, type)) {
+            errors.push({
+                ...at,
+                message: `unknown alert type ${match[1]}; use NOTE, TIP, IMPORTANT or WARNING`,
+            });
+            continue;
+        }
+        const raw = match[2].trim();
+        let parsed = { id: "", classes: [], values: {}, problems: [] };
+        if (raw) {
+            if (!/^\{.*\}$/.test(raw))
+                parsed.problems.push(
+                    "alert attributes need {…} braces immediately after the marker",
+                );
+            else parsed = parseExtensionAttributes(raw.slice(1, -1));
+        }
+        for (const message of [...parsed.problems, ...refusedAttributes(parsed.values)])
+            errors.push({ ...at, message });
+        const body = lines
+            .slice(start + 1, after)
+            .map((line) => {
+                for (let level = 0; level < depth; level++)
+                    line = line.replace(/^ {0,3}>[ \t]?/, "");
+                return line;
+            })
+            .join("\n")
+            .trimEnd();
+        if (!body.trim())
+            errors.push({ ...at, message: `${ALERT_TYPES[type].title} alert needs a body` });
+        const attributes = Object.fromEntries(
+            Object.entries(parsed.values).filter(
+                ([key, value]) => !refusedAttributes({ [key]: value }).length,
+            ),
+        );
+        const title = attributes.title ?? ALERT_TYPES[type].title;
+        delete attributes.title;
+        blocks.push({
+            start,
+            end: after - 1,
+            depth,
+            type,
+            title,
+            id: parsed.id,
+            classes: parsed.classes,
+            attributes,
+            body,
+        });
+    }
+    return { blocks, errors };
+}
+/** Render alert wrappers while preserving ordinary Markdown and note footnotes.
+ * @param {string} source - Authored Markdown.
+ * @param {"web"|"foundry"} [target="web"] - Publishing surface.
+ */
+export function renderAlerts(source, target = "web") {
+    const { blocks, errors } = scanAlerts(source),
+        lines = String(source ?? "").split("\n"),
+        output = [];
+    let cursor = 0;
+    const escape = (value) =>
+        String(value)
+            .replace(/&/g, "&amp;")
+            .replace(/"/g, "&quot;")
+            .replace(/</g, "&lt;")
+            .replace(/>/g, "&gt;");
+    for (const block of blocks.filter(
+        (block) => !blocks.some((parent) => parent.start < block.start && parent.end >= block.end),
+    )) {
+        output.push(...lines.slice(cursor, block.start));
+        const attrs = [
+            `class="${escape(["alert", "alert-" + block.type, ...block.classes].join(" "))}"`,
+        ];
+        if (block.id) attrs.push(`id="${escape(slugify(block.id))}"`);
+        for (const [key, value] of Object.entries(block.attributes))
+            attrs.push(`${key}="${escape(value)}"`);
+        const definition = ALERT_TYPES[block.type];
+        output.push(
+            "",
+            `<aside ${attrs.join(" ")}>`,
+            `<header class="alert-title">${definition.icon} ${titleParser.renderInline(block.title)}</header>`,
+            "",
+            renderAlerts(block.body, target).markdown,
+            "",
+            "</aside>",
+            "",
+        );
+        cursor = block.end + 1;
+    }
+    output.push(...lines.slice(cursor));
+    return { markdown: output.join("\n"), errors };
+}
+/** Mark alert blockquotes and remove their marker before inline parsing.
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function alertMarkdownPlugin(md) {
+    md.core.ruler.before("inline", "alert_markers", (state) => {
+        const alerts = scanAlerts(state.src).blocks;
+        const depths = new Map();
+        let depth = 0;
+        for (let i = 0; i < state.tokens.length; i++) {
+            if (state.tokens[i].type === "blockquote_open") depths.set(i, ++depth);
+            if (state.tokens[i].type === "blockquote_close") depth--;
+        }
+        for (let i = state.tokens.length - 1; i >= 0; i--) {
+            const token = state.tokens[i];
+            if (token.type !== "blockquote_open") continue;
+            const block = alerts.find(
+                (block) => token.map?.[0] === block.start && depths.get(i) === block.depth,
+            );
+            if (!block) continue;
+            token.meta = { ...token.meta, alert: block };
+            const inline = state.tokens[i + 2];
+            if (state.tokens[i + 1]?.type !== "paragraph_open" || inline?.type !== "inline")
+                continue;
+            const newline = inline.content.indexOf("\n");
+            if (newline < 0) state.tokens.splice(i + 1, 3);
+            else {
+                inline.content = inline.content.slice(newline + 1);
+                if (inline.map) inline.map[0]++;
+            }
+        }
+    });
+}