@heroiclands/package-build 22.20.0 → 22.22.0

package/engine/frontmatter-lint.mjs

@@ -60,6 +60,7 @@ import {
     CHARACTER_NAME_KEYS,
     NOTE_NAME_KEYS,
     NOTE_TOP_LEVEL_KEY_SET,
+    NOTE_TOP_LEVEL_KEYS,
 } from "./note-frontmatter.mjs";
 import { AddressEntries } from "./address-values.mjs";
 import { addressPositions } from "./note-addresses.mjs";
@@ -291,6 +292,21 @@ function distance(a, b) {
     return prev[cols - 1];
 }
 
+/**
+ * A closed vocabulary as an English list, for the message that names it.
+ *
+ * Written from the declaration rather than spelled into the message, so a key
+ * the vocabulary gains cannot go unmentioned by the finding that refuses its
+ * neighbours.
+ *
+ * @param {readonly string[]} keys - The declared keys, in declared order.
+ * @returns {string} `"a, b, or c"`.
+ */
+function listed(keys) {
+    if (keys.length < 2) return keys.join("");
+    return `${keys.slice(0, -1).join(", ")}, or ${keys[keys.length - 1]}`;
+}
+
 /**
  * The declared key an unknown one was most likely meant to be.
  *
@@ -357,6 +373,18 @@ export function matchesKind(value, kind, context = {}) {
             // this answers is whether the value has one of the two shapes the
             // field admits. A list has neither.
             return matchesKind(value, "string") || matchesKind(value, "map");
+        case "string-or-list":
+            // One value or several of the same kind. Unlike `list-or-map` the
+            // two halves say the same thing at different lengths, so either is
+            // accepted here and the entries are read by the field's own check.
+            return matchesKind(value, "string") || Array.isArray(value);
+        case "list-or-map":
+            // A list, or a map. The two carry different facts rather than
+            // being two spellings of one — a map keyed by Address says what is
+            // true *of* each key, which a list has nowhere to put — so the
+            // field's own check is what reads the entries, and all this
+            // answers is whether the value has one of the two shapes.
+            return Array.isArray(value) || matchesKind(value, "map");
         default:
             return true;
     }
@@ -408,9 +436,8 @@ function dataBlock(fm) {
  * Check a note's `data:` container against the closed vocabulary its type
  * declares.
  *
- * Unlike the top level, which is passed through to the published page and so
- * cannot be refused, `data:` holds the type-specific facts about the subject
- * and every key of it is declared. An unrecognised key is therefore a finding
+ * `data:` holds the type-specific facts about the subject, and every key of it
+ * is declared by the note's type. An unrecognised key is therefore a finding
  * naming the note, with the key it was most likely meant to be — the same
  * capped edit distance {@link nearest} applies to a `sohl:` key, drawn from
  * this type's own vocabulary rather than from every type's.
@@ -485,8 +512,8 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
                 type === "affiliation" && key === "commonSkills" ?
                     "`data.commonSkills` is not an affiliation field; write skill Addresses at `sohl.system.commonSkills`"
                 :   `"${key}" is not a \`data:\` property declared by ${type}; ` +
-                    `the container is closed, so unlike a top-level key it is ` +
-                    `not passed through to the page` +
+                    `the container is closed, so the key reaches no document ` +
+                    `and no page` +
                     (guess ? `. Did you mean "${guess}"?` : ""),
         });
     }
@@ -539,7 +566,13 @@ function checkDataContainer(note, { type, fields, packs, addressContext, index }
 function checkDataReferences(note, field, value, segments, context, index) {
     const checks = [];
     if (field.kind === "address") checks.push({ value, path: [], kind: "address" });
-    if (field.entryKind) {
+    // A `list-or-map` field declares both halves, and each describes one shape:
+    // `entryKind` the list's entries, `keyKind` the map's keys. Reading both of
+    // one value would check a map's standings as if they were Addresses and a
+    // list's indices as if they were its keys.
+    const dual = field.kind === "list-or-map";
+    const written = Array.isArray(value) ? "list" : "map";
+    if (field.entryKind && !(dual && written === "map")) {
         if (Array.isArray(value)) {
             value.forEach((entry, i) =>
                 checks.push({ value: entry, path: [i], kind: field.entryKind }),
@@ -551,7 +584,7 @@ function checkDataReferences(note, field, value, segments, context, index) {
             });
         } else checks.push({ value, path: [], kind: field.entryKind });
     }
-    if (field.keyKind) {
+    if (field.keyKind && !(dual && written === "list")) {
         if (value instanceof AddressEntries) {
             for (const entry of value.entries)
                 checks.push({
@@ -874,9 +907,9 @@ function checkSubType(note, { type, entry }) {
 /**
  * Check a note's `tags` for near misses against the tags that classify.
  *
- * `tags:` is top-level and the top level is open, so an unrecognised tag is
- * **not** a finding: a theme, a region or a working state is the author's own
- * vocabulary and this build has no standing to refuse it.
+ * `tags:` is a closed key holding an open vocabulary of values, so an
+ * unrecognised tag is **not** a finding: a theme, a region or a working state
+ * is the author's own vocabulary and this build has no standing to refuse it.
  *
  * **Distance alone is not enough either**, which the corpus settles rather than
  * argues: `azravan` on a faith, `barter` on an economy note and `secret` on
@@ -976,13 +1009,10 @@ function inBlockKeys(schema) {
  * note-level field either, and a check about the note-level field must not read
  * it.
  *
- * `affiliation`'s `title` is the case that named this. A note's top-level
- * `title` is its page heading, which the site emitter publishes as
- * `fm.title ?? name`; `sohl.title` is the style of address an office carries —
- * "Ajaw", "Warden". Twenty-eight `sohl-kethira-basic` affiliations author
- * `sohl.title: ""` — an office with no style of address, which is ordinary —
- * and every one of them was reported as publishing a page with no heading. None
- * of them does; their pages take `name.full` exactly as intended.
+ * `affiliation`'s `commonSkills` is the case to read it against: the skills
+ * common among a society's members belong to the SoHL affiliation item, so
+ * nothing outside that item supplies them and a note-level check must not go
+ * looking in the block for one.
  *
  * Keyed on the **in-block** key — `legacyKey` where a field declares one, and
  * its first segment where that is dotted — because that is the position a note
@@ -1349,26 +1379,16 @@ export function lintNote(
     // it. It is transitional in the same sense — `""` is a legal thing to mean,
     // and the message says so, but nothing in any tree means it yet.
     //
-    // **These two only, never `title`.** The rule reads as a general one about
-    // optional strings, and it is not — it belongs to `resolveImg`, and `title`
-    // never goes through it.
-    //
-    // It once had a sharper reason: a note's top-level `title` was
-    // simultaneously the shared source for an `affiliation` item's
-    // `system.title`, so asking an author for `title: null` would have compiled
-    // the literal string `"null"` into the document. The field declares
-    // `topLevelMeans` now, so the top-level key is no longer a source for it and
-    // `title: null` is harmless. `title: ""` is warned about on its own account
-    // below, as the *page's* heading rather than as an art path.
+    // **The art slots only.** The rule reads as a general one about optional
+    // strings, and it is not — it belongs to `resolveImg`, and nothing else
+    // goes through it.
     //
-    // **The collision itself did not go away, and this was where that was
-    // misread.** `topLevelMeans` settles which position the *emitted field*
-    // reads; it says nothing about which position a *check* reads, and
-    // `authoredValue` went on resolving through the block regardless — so an
-    // office with no style of address answered for its note's heading, in
-    // twenty-eight `sohl-kethira-basic` affiliations. Hence
-    // `blockCollisions`: a note-level check reads past a block key its type
-    // claims for something else.
+    // **A block key a type claims for something else is read past.**
+    // `topLevelMeans` settles which position the *emitted field* reads; it says
+    // nothing about which position a *check* reads, and `authoredValue` would
+    // go on resolving through the block regardless — so an office with no style
+    // of address would answer for a note's art, in twenty-eight
+    // `sohl-kethira-basic` affiliations. Hence `blockCollisions`.
 
     // The template priority is a *shared source* — the specification states it
     // once for every type, as it does `pack` — so its retirement is reported
@@ -1495,35 +1515,6 @@ export function lintNote(
                 "meant to have no image",
         });
     }
-    // `title: ""` publishes a blank heading. The rule the art fields
-    // follow — `null` falls back, `""` is blank on purpose — reads the same way
-    // here, and for a *page heading* the deliberate blank is almost never what
-    // anyone wants: the emitter is `fm.title ?? name`, so `""` survives, the
-    // page publishes with no name, and it sorts to the front of its section
-    // landing ahead of every named page. Fifteen notes in `sohl-thalorna` are
-    // in exactly that state.
-    //
-    // A warning rather than an error: the value is legal under the rule, and a
-    // note that genuinely wants no heading may keep it — it just has to mean it.
-    //
-    // **The emitter reads `fm.title`, so this reads the note level.** On an
-    // `affiliation` `sohl.title` is the office's style of address, which the
-    // heading has nothing to do with — and `blockCollisions` is what keeps the
-    // two apart. On every other type nothing claims the block key, so the
-    // resolution is the unchanged one.
-    if (authoredValue(fm, "title", { blockCollides: blockCollisions.has("title") }) === "") {
-        findings.push({
-            file: note.file,
-            ...at("title"),
-            severity: "warning",
-            message:
-                '`title: ""` publishes a page with no heading, which sorts to ' +
-                "the front of its section ahead of every named page. Write " +
-                "`title: null` to fall back to `name.full`, or give the page a " +
-                'heading; keep `""` only where the blank is meant',
-        });
-    }
-
     if (Object.hasOwn(fm, "draft")) {
         findings.push({
             file: note.file,
@@ -1606,11 +1597,16 @@ export function lintNote(
         ) {
             continue;
         }
+        const guess = nearest(key, NOTE_TOP_LEVEL_KEYS);
         findings.push({
             file: note.file,
             ...position,
             severity: "error",
-            message: `unknown top-level frontmatter key ${JSON.stringify(key)}; use shortcode, name, type, subType, description, tags, data, hm3, or sohl`,
+            message:
+                `unknown top-level frontmatter key ${JSON.stringify(key)}; ` +
+                `the region is closed, so the key reaches no document and no ` +
+                `page. Use ${listed(NOTE_TOP_LEVEL_KEYS)}` +
+                (guess ? `. Did you mean "${guess}"?` : ""),
         });
     }
 

package/engine/frontmatter.mjs

@@ -309,14 +309,14 @@ export function resolveRelation(fm, ctx = "item") {
  *
  * @param {object} fm - The item frontmatter.
  * @param {string} [ctx] - Optional label for the error (defaults to the item's
- *   title/name, else "item").
+ *   display name, else "item").
  * @returns {string} The declared subType.
  * @throws {Error} When `subType` is missing or blank.
  */
 export function requireSubType(fm, ctx) {
     const subType = sohlSystemField(fm, "subType", undefined);
     if (subType == null || subType === "") {
-        const label = ctx || fm?.title || fm?.name || "item";
+        const label = ctx || fm?.name?.full || "item";
         throw new Error(
             `${label}: missing required 'subType' — every subType-bearing item must declare its kind (the builder substitutes no default).`,
         );
@@ -379,7 +379,7 @@ export function parseValueDesc(raw) {
  *   two spellings, and there is only one left to be.
  */
 export function folderField(fm) {
-    const asAddress = fm?.sohl?.packFolder ?? fm?.data?.packFolder ?? fm?.packFolder ?? null;
+    const asAddress = fm?.sohl?.packFolder ?? fm?.data?.packFolder ?? null;
     if (asAddress != null && asAddress !== "") return { value: asAddress, isAddress: true };
     return { value: null, isAddress: true };
 }

package/engine/heading-attributes.mjs

@@ -0,0 +1,308 @@
+/* SPDX-License-Identifier: GPL-3.0-or-later */
+
+/**
+ * The braced attribute block a heading may end with, read once.
+ *
+ * ```
+ * # The Harbor {#harbor .wide}
+ * ```
+ *
+ * The index, the link checker, the journal compiler, the caption pass and the
+ * book all ask what a heading declares, and they have to give the same answer:
+ * an id a surface publishes as an anchor, classes a surface may honour, and
+ * attributes an HTML surface writes onto the element. This is where that
+ * reading lives, so there is one grammar — the same one a `:::` block and a
+ * `:::caption` are written in.
+ *
+ * **A leaf, deliberately.** `anchors.mjs` is shared by the compilers, the index
+ * and the link checker and cannot import any of them; the caption pass is
+ * imported by `anchors.mjs` and so cannot import it back. A module that imports
+ * only the attribute grammar can be asked by all of them.
+ *
+ * @module
+ */
+
+import { parseExtensionAttributes, refusedAttributes } from "./extension-attributes.mjs";
+
+/**
+ * A heading line: its hashes and the text after them.
+ *
+ * Shared with every pass that has to find a heading before reading what it
+ * declares, so the passes cannot disagree about which lines are headings.
+ */
+export const HEADING_LINE = /^\s*(#{1,6})\s+(.+?)\s*#*\s*$/;
+
+/** The braces a heading's text may end with, and what is inside them. */
+const SUFFIX = /^(.*?)\s*\{([^}\n]*)\}\s*$/;
+
+/**
+ * A heading's id.
+ *
+ * Looser than a caption's or a block's, which must begin with a letter: a
+ * heading's id is published as an HTML `id` and as a Foundry page anchor, both
+ * of which admit a digit first, and the corpus carries ids that are Foundry
+ * document ids and ids derived from a numbered heading.
+ */
+const HEADING_ID = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+
+/**
+ * Read a heading's text and the attribute block it may end with.
+ *
+ * A suffix that is not an attribute block — a set written in braces, a die
+ * expression — is left in the text and reported, so no surface silently prints
+ * a heading with words missing and no author is told to fix nothing.
+ *
+ * **One mistake draws one finding.** Braces holding nothing the grammar
+ * recognises are reported once, naming the braces: an author who wrote
+ * `{a, b}` meant no attribute block at all, and a complaint per fragment inside
+ * it says the same thing twice in words that name neither the heading nor the
+ * fix. Braces that *are* an attribute block, carrying one bad attribute beside
+ * good ones, relay the grammar's own complaint about that attribute.
+ *
+ * @param {string} heading - A heading's text, hashes already removed.
+ * @returns {{text: string, id: string, classes: string[],
+ *   values: Record<string, string>, problems: string[], braces: boolean}}
+ *   `text` is what a surface sets, `braces` whether a suffix was there at all.
+ */
+export function splitHeadingAttributes(heading) {
+    const raw = String(heading ?? "").trim();
+    const blank = { text: raw, id: "", classes: [], values: {}, problems: [], braces: false };
+    const match = SUFFIX.exec(raw);
+    if (!match) return blank;
+    const parsed = parseExtensionAttributes(match[2], { idPattern: HEADING_ID });
+    const recognised =
+        Boolean(parsed.id) || parsed.classes.length > 0 || Object.keys(parsed.values).length > 0;
+    let problems;
+    if (recognised) {
+        // An id, a class or an attribute the markup owns: refused here as it is
+        // on a named block, because a heading writes its attributes onto the
+        // element on both HTML surfaces.
+        problems = [...parsed.problems, ...refusedAttributes(parsed.values)];
+    } else if (match[2].trim()) {
+        problems = [`{${match[2]}} is not an attribute block`];
+    } else {
+        problems = ["an attribute block states nothing"];
+    }
+    if (problems.length) return { ...blank, braces: true, problems };
+    return {
+        text: match[1].trim(),
+        id: parsed.id,
+        classes: parsed.classes,
+        values: parsed.values,
+        problems: [],
+        braces: true,
+    };
+}
+
+/**
+ * The class that withholds a section from players.
+ *
+ * Written on the heading that opens the section, so the section stays linkable:
+ * secrecy is a property of the section, not of the name a link resolves to.
+ */
+export const WITHHELD_CLASS = "secret";
+
+/**
+ * Whether a heading opens a journal page.
+ *
+ * A Foundry UUID addresses a page and nothing smaller, so a section a link can
+ * reach has to be one: a top-level heading starts a page, and so does any
+ * heading that names an anchor. {@link module:engine/journals.splitPages}
+ * decides *where* a page begins — a captioned heading and a heading inside a
+ * fence or a named block are its business — and asks this which headings are
+ * eligible, so no caller re-decides it.
+ *
+ * @param {{level: number, id: string}} heading - From
+ *   {@link scanHeadingAttributes}, or any `{level, id}` pair.
+ * @returns {boolean} Whether the heading opens a page.
+ */
+export function opensPage({ level, id }) {
+    return level === 1 || Boolean(id);
+}
+
+/**
+ * Every heading in a body, with what its attribute block declares.
+ *
+ * Fenced code is skipped: `#` opens a comment in most of what gets fenced, and
+ * an example heading in a document is not a heading of it.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on, so a
+ *   finding lands where an editor can open it.
+ * @returns {{headings: Array<{level: number, line: number, text: string,
+ *   id: string, classes: string[], values: Record<string, string>}>,
+ *   errors: Array<{line: number, column: number, message: string}>}}
+ */
+export function scanHeadingAttributes(source, bodyLine = 1) {
+    const lines = String(source ?? "").split("\n");
+    const headings = [];
+    const errors = [];
+    let codeFence = null;
+    for (let i = 0; i < lines.length; i++) {
+        const fence = /^ {0,3}(`{3,}|~{3,})/.exec(lines[i]);
+        if (codeFence) {
+            if (fence && fence[1][0] === codeFence[0] && fence[1].length >= codeFence.length)
+                codeFence = null;
+            continue;
+        }
+        if (fence) {
+            codeFence = fence[1];
+            continue;
+        }
+        const heading = HEADING_LINE.exec(lines[i]);
+        if (!heading) continue;
+        const parsed = splitHeadingAttributes(heading[2]);
+        const line = bodyLine + i;
+        if (parsed.problems.length) {
+            const column = lines[i].indexOf("{") + 1;
+            for (const message of parsed.problems) errors.push({ line, column, message });
+            continue;
+        }
+        headings.push({
+            level: heading[1].length,
+            line,
+            text: parsed.text,
+            id: parsed.id,
+            classes: parsed.classes,
+            values: parsed.values,
+        });
+    }
+    return { headings, errors };
+}
+
+/**
+ * A markdown-it plugin writing a heading's attribute block onto its element.
+ *
+ * The website's renderer reads the block itself, so the surfaces that use
+ * markdown-it read it here and publish the same `id`, the same classes and the
+ * same attributes — rather than typesetting the braces an author wrote.
+ *
+ * @param {object} md - A markdown-it instance.
+ * @returns {void}
+ */
+export function headingAttributesPlugin(md) {
+    md.core.ruler.push("heading_attributes", (state) => {
+        const tokens = state.tokens;
+        for (let i = 0; i < tokens.length; i++) {
+            if (tokens[i].type !== "heading_open") continue;
+            const inline = tokens[i + 1];
+            const children = inline?.children ?? [];
+            const last = children[children.length - 1];
+            if (last?.type !== "text") continue;
+            const parsed = splitHeadingAttributes(String(last.content ?? ""));
+            if (!parsed.braces || parsed.problems.length) continue;
+            last.content = parsed.text;
+            inline.content = splitHeadingAttributes(String(inline.content ?? "")).text;
+            if (parsed.id) tokens[i].attrSet("id", parsed.id);
+            if (parsed.classes.length) tokens[i].attrJoin("class", parsed.classes.join(" "));
+            for (const [key, value] of Object.entries(parsed.values)) tokens[i].attrSet(key, value);
+        }
+    });
+}
+
+/**
+ * Parse one line as a heading, and say whether it starts a journal page.
+ *
+ * The single reading of that rule. {@link module:engine/journals.splitPages}
+ * builds its pages from it; `scanBlocks` and `scanCaptions` refuse a heading
+ * that starts a page written where it cannot become one. All three ask this, so
+ * none of them can disagree about what a heading line means or about what starts
+ * a page — and the attribute block comes off here, so a class beside an anchor
+ * is not read as part of the anchor by any of them.
+ *
+ * @param {string} line - One line of a note's body.
+ * @returns {{level: number, text: string, id: string, classes: string[],
+ *   values: Record<string, string>, problems: string[], startsPage: boolean}|null}
+ *   `null` when the line is not a heading.
+ */
+export function parseHeadingLine(line) {
+    const heading = HEADING_LINE.exec(line);
+    if (!heading) return null;
+    const level = heading[1].length;
+    const parsed = splitHeadingAttributes(heading[2]);
+    return {
+        level,
+        text: parsed.text,
+        id: parsed.id,
+        classes: parsed.classes,
+        values: parsed.values,
+        problems: parsed.problems,
+        startsPage: opensPage({ level, id: parsed.id }),
+    };
+}
+
+/**
+ * Every heading that opens a journal page, by the line it sits on.
+ *
+ * The walk that decides it: fenced code holds no headings, a named block holds
+ * no page — the block is one passage of the page it is written in — and what is
+ * left is read by {@link opensPage}. {@link module:engine/journals.splitPages}
+ * builds the pages from this, and the passes that honour a class on a
+ * page-opening heading ask the same question of the same answer.
+ *
+ * A caption also opens a page, which is `splitPages`' business: a caption is
+ * found by the caption pass, and a heading it captions is listed here and
+ * dropped there.
+ *
+ * @param {string} source - A note's markdown body.
+ * @returns {Map<number, {level: number, line: number, text: string, id: string,
+ *   classes: string[], values: Record<string, string>}>} Keyed by 0-based line.
+ */
+export function pageOpenings(source) {
+    const lines = String(source ?? "").split("\n");
+    const openings = new Map();
+    let inCodeBlock = false;
+    let inBlock = false;
+    for (const [index, line] of lines.entries()) {
+        if (line.trim().startsWith("```")) inCodeBlock = !inCodeBlock;
+        if (!inCodeBlock && /^:::secret[ \t]*$/.test(line)) inBlock = true;
+        else if (!inCodeBlock && /^:::[ \t]*$/.test(line)) inBlock = false;
+        if (inCodeBlock || inBlock) continue;
+        const heading = parseHeadingLine(line);
+        if (!heading?.startsPage) continue;
+        openings.set(index, { ...heading, line: index + 1 });
+    }
+    return openings;
+}
+
+/**
+ * The spans a `.secret` heading withholds, and the classes written where no
+ * surface can honour them.
+ *
+ * A span runs from its heading to the line before the next heading that opens a
+ * page, which is the stretch Foundry makes one page of. A `.secret` on a heading
+ * that opens no page covers no page, so no surface can withhold it: that is a
+ * finding at the heading's own line rather than a class quietly ignored.
+ *
+ * @param {string} source - A note's markdown body.
+ * @param {number} [bodyLine=1] - The 1-based file line the body starts on.
+ * @returns {{sections: Array<{start: number, end: number, heading: object}>,
+ *   errors: Array<{line: number, column: number, message: string}>}} `start` and
+ *   `end` are 0-based line indexes, `end` exclusive.
+ */
+export function withheldSections(source, bodyLine = 1) {
+    const lines = String(source ?? "").split("\n");
+    const openings = pageOpenings(source);
+    const starts = [...openings.keys()];
+    const sections = [];
+    const errors = [];
+    for (const [at, index] of starts.entries()) {
+        const heading = openings.get(index);
+        if (!heading.classes.includes(WITHHELD_CLASS)) continue;
+        sections.push({ start: index, end: starts[at + 1] ?? lines.length, heading });
+    }
+    // A heading that opens no page is not among the openings at all, so the
+    // class is looked for again across every heading the body states.
+    for (const heading of scanHeadingAttributes(source, bodyLine).headings) {
+        if (openings.has(heading.line - 1)) continue;
+        if (!heading.classes.includes(WITHHELD_CLASS)) continue;
+        errors.push({
+            line: heading.line,
+            column: (lines[heading.line - bodyLine]?.indexOf("{") ?? 0) + 1,
+            message:
+                `.${WITHHELD_CLASS} withholds the page a heading opens, and this heading ` +
+                "opens none — give it an anchor, or raise it to the top level",
+        });
+    }
+    return { sections, errors };
+}

package/engine/helpers.mjs

@@ -26,6 +26,7 @@
  */
 
 import { buildReferenceTargets } from "./reference-targets.mjs";
+import { standingsDigest } from "./standings.mjs";
 
 import { decodeNoteAddresses } from "./note-addresses.mjs";
 import { positionOfYamlPath } from "./diagnostics.mjs";
@@ -64,8 +65,8 @@ import { linkFindingMessage } from "./wikilink-syntax.mjs";
 import { isDraftNote } from "./note-vocabulary.mjs";
 import { DERIVED_PACKED_TYPES, NEVER_PACKED_TYPES } from "./note-claims.mjs";
 import { expandContentTables } from "./content-tables.mjs";
-import { renderSecretBlocks } from "./content-secrets.mjs";
-import { renderAdmonitions } from "./content-admonitions.mjs";
+import { renderBlocks } from "./content-blocks.mjs";
+import { headingAttributesPlugin } from "./heading-attributes.mjs";
 import { renderCaptionBlocks, scanCaptions } from "./content-captions.mjs";
 import { positionInBody } from "./diagnostics.mjs";
 // The pure `sohl:` frontmatter readers live in a leaf module so the item-type
@@ -94,6 +95,9 @@ export {
 export const md = markdownit({ html: true })
     .use(footnotePlugin)
     .use(deflistPlugin)
+    // A heading's attribute block, written onto the heading element rather than
+    // typeset into it — the reading the website's renderer does for itself.
+    .use(headingAttributesPlugin)
     .use(
         // Resolved per render, not at import: this constant is built before any
         // configuration is read, and a package's own icons live in the
@@ -151,15 +155,10 @@ md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
     return `<li id="fn${id}" class="footnote-item" value="${number}">`;
 };
 
-/** Render a note body with Foundry's secret section markup. */
+/** Render a note body with Foundry's named-block markup. */
 export function renderFoundryMarkdown(body, captions, footnoteNumbers, docId) {
-    const { markdown } = renderSecretBlocks(body, "foundry", (inner) => md.render(inner));
-    const admonitions = renderAdmonitions(markdown, (inner) => md.render(inner));
-    const captioned = renderCaptionBlocks(
-        admonitions.markdown,
-        (block) => md.render(block),
-        captions,
-    );
+    const blocks = renderBlocks(body, "foundry");
+    const captioned = renderCaptionBlocks(blocks.markdown, (block) => md.render(block), captions);
     return md.render(captioned.markdown, { footnoteNumbers, docId });
 }
 
@@ -834,6 +833,10 @@ export function buildContentLinkIndex(
             // can group by the family its target declares rather than only by
             // where the target lives.
             subType: fm.subType ?? null,
+            // The rungs and posts this body confers, carried for the same
+            // reason: a being holds a rank as a number, and the body is where
+            // what that number is called is declared.
+            standings: standingsDigest(fm) ?? null,
             name: fm.name?.full ?? base,
             // Whether the note is tagged `draft`. Read from the tag
             // vocabulary that declares it, and used for one thing: a link
@@ -1030,18 +1033,21 @@ export function convertNoteWikilinks(
 /* ------------------------------------------------------------------------ */
 
 /**
- * Expand prepared SQL tables before resolving wikilinks in generated cells.
+ * Expand prepared SQL tables and page lists before resolving wikilinks in the
+ * links they generate.
  * @param {string} body - The note body.
- * @param {object} ctx - Source and prepared query results.
+ * @param {object} ctx - Source and prepared results.
  * @param {string} ctx.name - Name used in diagnostics.
  * @param {number} [ctx.bodyLine] - The first body line in the source file.
  * @param {object[]} [ctx.sqlTables] - Prepared SQL results in document order.
+ * @param {object[]} [ctx.pageLists] - Prepared page lists in document order.
  * @returns {{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}
  */
-export function expandNoteTables(body, { name, bodyLine, sqlTables }) {
+export function expandNoteTables(body, { name, bodyLine, sqlTables, pageLists }) {
     const { markdown, errors, lineMap } = expandContentTables(body ?? "", {
         source: name,
         sqlTables,
+        pageLists,
     });
     if (errors.length) {
         const err = new Error(errors.map((e) => `content table — ${e.reason}`).join("; "));