@heroiclands/package-build 22.21.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,11 @@ 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
@@ -415,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.
@@ -492,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}"?` : ""),
         });
     }
@@ -887,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
@@ -989,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
@@ -1362,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
@@ -1508,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,
@@ -1619,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

@@ -65,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
@@ -95,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
@@ -152,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 });
 }
 
@@ -1035,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("; "));

package/engine/homepage.mjs

@@ -131,12 +131,12 @@ export function isHomepage(fm) {
  * `name` and `shortcode` are permitted: the shortcode is what a link is
  * written with, and `name` titles the page like every other note's.
  *
- * **A named class, not an allow-list, and that boundary is the decision.** A
- * homepage's frontmatter is *emitted into the published page*
- * ({@link homepageFrontmatter}), so an unrecognised key is a Hugo or theme
- * parameter this build has never heard of and has no standing to refuse.
- * Rejecting unknown keys would make every new theme parameter wait on a
- * package-build release.
+ * **A named class, not an allow-list, and that boundary is the decision.**
+ * What this class answers is a key the top-level vocabulary *accepts* and a
+ * homepage still cannot use, which is a different question from an unknown
+ * key: the frontmatter lint refuses those for every note alike, naming the
+ * closed vocabulary, so repeating that judgement per type would be a second
+ * answer to one question.
  *
  * `aliases` is deliberately not in the class: it is a **retired** field, refused
  * on every note whatever its type, so it is answered there rather than
@@ -340,7 +340,7 @@ function positionOfType(file) {
  * `packageBuild.manifest.title` — the name Foundry already shows for the
  * package — so a homepage that adds nothing to it need not restate it. An
  * authored `name.full` wins, because a front page may greet a reader
- * differently from a package browser. A top-level `title` is also readable.
+ * differently from a package browser.
  *
  * Falls back to `contentPackage` last, so a package that has no manifest of its
  * own still yields a titled page rather than a blank heading.
@@ -350,7 +350,7 @@ function positionOfType(file) {
  * @returns {string} The title.
  */
 export function homepageTitle(fm, config) {
-    const authored = fm?.name?.full ?? fm?.title;
+    const authored = fm?.name?.full;
     if (typeof authored === "string" && authored.trim()) return authored;
     const manifest = /** @type {Record<string, unknown>|undefined} */ (
         config?.packageBuild?.manifest

package/engine/index.mjs

@@ -220,6 +220,9 @@ export * as contentHtml from "./content-html.mjs";
 /** An image saying how wide it is and where it sits, in two closed vocabularies. */
 export * as contentImages from "./content-images.mjs";
 
+/** A list item opened with `[ ]` or `[x]`, which every surface reads as text. */
+export * as contentTaskLists from "./content-tasklists.mjs";
+
 /** `![[…]]` — the wikilink that renders a picture where it stands. */
 export * as contentEmbeds from "./content-embeds.mjs";