@heroiclands/package-build 22.21.0 → 22.23.0

package/engine/content-format-check.mjs

@@ -104,6 +104,9 @@ import { authoredFields } from "./field-spec.mjs";
 import { positionInFrontmatter } from "./diagnostics.mjs";
 import { RETIRED_FIELD_ALIASES } from "./retired-fields.mjs";
 import { authoredKey } from "./system-block.mjs";
+// The top-level vocabulary, read rather than restated — a second list of the
+// keys a note's own identity uses is one more thing to drift.
+import { NOTE_TOP_LEVEL_KEY_SET } from "./note-vocabulary.mjs";
 
 /**
  * Every field path any subtype of a published schema declares.
@@ -273,18 +276,18 @@ function nearest(key, candidates) {
 /**
  * Top-level keys the format names as the note's own, whatever its type.
  *
- * Top level is otherwise **open** — an unrecognised key there is a Hugo or
- * theme parameter this build has no standing to refuse — so this set exists
- * only to keep a note's own identity fields from being mistaken for a
- * misplaced `data` property where the two share a name. `type` and `subType`
- * are the pair that matters: several mapping tables name `subType` as a shared
- * source, and it is authored at top level by design.
+ * The top-level vocabulary itself, read rather than restated: this set exists
+ * to keep a note's own identity fields from being mistaken for a misplaced
+ * `data` property where the two share a name, and the keys that are a note's
+ * own are exactly the ones the region declares. `type` and `subType` are the
+ * pair that matters — several mapping tables name `subType` as a shared source,
+ * and it is authored at top level by design. A key the region does *not*
+ * declare, such as `id` beside `data.id`, is reported as the misplaced `data`
+ * property it is.
  *
  * @type {ReadonlySet<string>}
  */
-export const NOTE_LEVEL_KEYS = Object.freeze(
-    new Set(["id", "type", "subType", "shortcode", "description", "tags", "name"]),
-);
+export const NOTE_LEVEL_KEYS = NOTE_TOP_LEVEL_KEY_SET;
 
 /** Whether a value is a plain object a block could be written as. */
 function isBlock(value) {
@@ -379,9 +382,9 @@ export function measureNote(note, format, { severity = "warning" } = {}) {
     }
 
     // The two regions a shared source is written in today, and neither is where
-    // the format puts it. Top level is open in general — but a key the type's
-    // own table declares is not an unrecognised one, it is one whose home the
-    // format states.
+    // the format puts it. A key the type's own table declares is not merely an
+    // unrecognised one — it is one whose home the format states, so the finding
+    // names that home rather than the vocabulary.
     for (const key of spec.dataKeys) {
         if (NOTE_LEVEL_KEYS.has(key)) continue;
         if (Object.hasOwn(fm, key)) {

package/engine/content-format.yaml

@@ -242,7 +242,7 @@ types:
             - namedDays
             - eras
             - formats
-            - event
+            - events
         subTypes:
             - cosmology
             - deity

package/engine/content-images.mjs

@@ -58,10 +58,12 @@
  * agree: a figure is a block on all three, and nothing has to decide what a
  * floated run of text inside a paragraph would mean.
  *
- * **The alt text is the caption.** Print has no `alt` attribute and has to put
- * those words somewhere visible; rather than one surface showing them and two
- * hiding them, every surface draws them under the picture, and the HTML
- * surfaces carry them as `alt` as well.
+ * **Alt text renders as a caption on no surface.** A caption is drawn only for
+ * an image inside a `:::figure` fence that carries an authored caption, and the
+ * text drawn is always that caption. An image with no fence, or a fence with no
+ * caption, draws no line under the picture anywhere. The HTML surfaces still
+ * carry the alt text as the `img` element's `alt` attribute, for the reader a
+ * screen reader serves.
  *
  * ## Where the address resolves
  *
@@ -79,7 +81,9 @@ import path from "node:path";
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { parseExtensionAttributes } from "./extension-attributes.mjs";
 import { positionInBody } from "./diagnostics.mjs";
+import { FOOTNOTE_REFERENCE } from "./content-footnotes.mjs";
 import { foundryAddressProblem, pathnameProblem, servesFoundry } from "./pathnames.mjs";
+import { ASSET_ROLES } from "./asset-index.mjs";
 
 /**
  * The width classes an image may carry, and what each means to a renderer.
@@ -273,13 +277,27 @@ export function parseImageDirective(raw) {
 }
 
 /**
- * The classes a figure carries, from a parsed directive.
+ * The class a picture's role names, or `""` for no role or one outside the
+ * closed set — the same silent-degrade rule every other unrecognised value
+ * here gets, since a role this far downstream has already been validated or
+ * dropped by the asset record that carries it.
  *
- * @param {{classes?: string[], size?: string, float?: string}} [directive] - As parsed.
+ * @param {string} [role] - The role, from the resolved asset record.
+ * @returns {string} The class, or `""`.
+ */
+export function roleClass(role) {
+    return role && ASSET_ROLES.includes(role) ? `note-image-role-${role}` : "";
+}
+
+/**
+ * The classes a figure carries, from a parsed directive and its asset's role.
+ *
+ * @param {{classes?: string[], size?: string, float?: string, role?: string}} [directive] -
+ *   As parsed, plus the role the resolved asset record carries, if any.
  * @returns {string} A space-separated class list, always naming
  *   {@link IMAGE_FIGURE_CLASS} first.
  */
-export function figureClasses({ classes = [], size = "auto", float = "" } = {}) {
+export function figureClasses({ classes = [], size = "auto", float = "", role = "" } = {}) {
     const names = [IMAGE_FIGURE_CLASS];
     for (const name of classes) {
         const spec = IMAGE_CLASSES[/** @type {keyof typeof IMAGE_CLASSES} */ (name)];
@@ -288,6 +306,8 @@ export function figureClasses({ classes = [], size = "auto", float = "" } = {})
     if (size !== "auto" && IMAGE_SIZES.includes(size)) names.push(`note-image-size-${size}`);
     const position = IMAGE_FLOATS[/** @type {keyof typeof IMAGE_FLOATS} */ (float)];
     if (position) names.push(position.class);
+    const roleName = roleClass(role);
+    if (roleName) names.push(roleName);
     return names.join(" ");
 }
 
@@ -313,30 +333,85 @@ export function escapeHtml(text) {
  * function, so the two cannot drift into styling the same directive through
  * different class names.
  *
+ * **No `<figcaption>` is emitted here.** A `:::figure` fence draws its own
+ * label and authored caption around whatever this returns; the alt text stays
+ * on the `img` element alone.
+ *
+ * **The role class and the `width`/`height` attributes are what a stylesheet
+ * elsewhere keys a role's size on.** This module states none — the measure a
+ * `portrait` fills on a page is a Hugo theme's or a Foundry system's own
+ * decision — and emits only what the resolved asset record states: a role
+ * class when the picture declares one, and the attributes whenever the
+ * picture resolved to an asset record at all, blank for a vector. The
+ * attributes reserve the picture's own layout space before it loads, which is
+ * what lets a page avoid reflowing as pictures load in.
+ *
  * @param {object} image - The image.
  * @param {string} image.src - The address, resolved for the surface.
- * @param {string} [image.alt] - The alt text, which is also the caption.
+ * @param {string} [image.alt] - The alt text, for a reader who cannot see the
+ *   picture.
  * @param {string[]} [image.classes] - Width classes, from the directive.
  * @param {string} [image.size] - Named display size, from the directive.
  * @param {string} [image.float] - The float position, from the directive.
+ * @param {string} [image.role] - The picture's declared role, from the
+ *   resolved asset record.
+ * @param {number|""} [image.width] - The file's own pixel width, from the
+ *   resolved asset record; `""` for a vector. Omitted entirely when the
+ *   address resolved to no asset record at all.
+ * @param {number|""} [image.height] - As `width`.
  * @returns {string} The figure, as one HTML block.
  */
-export function imageFigureHtml({ src, alt = "", classes = [], size = "auto", float = "" }) {
-    const caption = alt ? `\n<figcaption>${escapeHtml(alt)}</figcaption>` : "";
+export function imageFigureHtml({
+    src,
+    alt = "",
+    classes = [],
+    size = "auto",
+    float = "",
+    role = "",
+    width,
+    height,
+}) {
+    const dims =
+        width !== undefined && height !== undefined ?
+            ` width="${escapeHtml(String(width))}" height="${escapeHtml(String(height))}"`
+        :   "";
     return (
-        `<figure class="${figureClasses({ classes, size, float })}">\n` +
-        `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}">${caption}\n` +
+        `<figure class="${figureClasses({ classes, size, float, role })}">\n` +
+        `<img src="${escapeHtml(src)}" alt="${escapeHtml(alt)}"${dims}>\n` +
         `</figure>`
     );
 }
 
+/**
+ * A body extension's own delimiter — a `:::` opener or closer, or a figure's
+ * `///`.
+ *
+ * It bounds a paragraph exactly as a blank line does: the line belongs to the
+ * construct rather than to the prose, and the pass that owns the construct
+ * hands its body on by itself. So a picture written tight against one is a
+ * block of its own, which is how `:::figure` is written.
+ */
+const DELIMITER = /^(?::{3,}[^\n]*|\/{3,}[ \t]*)$/;
+
+/**
+ * A footnote reference immediately trailing a match, anchored so it only
+ * consumes one sitting right against the end of it.
+ */
+const TRAILING_FOOTNOTE_REFERENCE = new RegExp(`^${FOOTNOTE_REFERENCE.source}`);
+
 /**
  * Whether a match sits alone in its own paragraph.
  *
- * "Alone" is the whole of a block: nothing else on its line, and a blank line
- * or the end of the body either side of it. A leading `>` or list marker
- * disqualifies it for the same reason a word does — the paragraph it belongs to
- * holds something the figure would have to be lifted out of.
+ * "Alone" is the whole of a block: nothing else on its line, and a blank line,
+ * a body-extension delimiter or the end of the body either side of it. A
+ * leading `>` or list marker disqualifies it for the same reason a word does —
+ * the paragraph it belongs to holds something the figure would have to be
+ * lifted out of.
+ *
+ * **A footnote reference trailing the match is not "other text."** `[^note]`
+ * annotates the picture rather than sitting beside it in prose, the same
+ * standing its own directive already has, so `![A ranger](r.webp)[^note]` is
+ * still alone.
  *
  * @param {string} text - The body the match indexes into.
  * @param {number} start - Where the match begins.
@@ -350,12 +425,18 @@ export function standsAlone(text, start, end) {
     // makes it an indented code block, which `matchAllOutsideCode` skips.
     if (!/^[ \t]*$/.test(src.slice(lineStart, start))) return false;
     const lineEnd = src.indexOf("\n", end);
-    if (!/^[ \t]*$/.test(src.slice(end, lineEnd === -1 ? src.length : lineEnd))) return false;
+    const afterMatch = src.slice(end, lineEnd === -1 ? src.length : lineEnd);
+    const reference = TRAILING_FOOTNOTE_REFERENCE.exec(afterMatch);
+    if (!/^[ \t]*$/.test(reference ? afterMatch.slice(reference[0].length) : afterMatch))
+        return false;
 
     const before = src.slice(0, lineStart);
-    if (before.trim() && !/\n[ \t]*\n[ \t]*$/.test(before)) return false;
+    const previous = before.replace(/\n$/, "").split("\n").pop() ?? "";
+    if (before.trim() && !/\n[ \t]*\n[ \t]*$/.test(before) && !DELIMITER.test(previous))
+        return false;
     const after = lineEnd === -1 ? "" : src.slice(lineEnd);
-    if (after.trim() && !/^\n[ \t]*\n/.test(after)) return false;
+    const next = after.replace(/^\n/, "").split("\n")[0] ?? "";
+    if (after.trim() && !/^\n[ \t]*\n/.test(after) && !DELIMITER.test(next)) return false;
     return true;
 }
 
@@ -414,6 +495,9 @@ export function imageSourcesIn(body) {
  * @param {object} [opts]
  * @param {number} [opts.bodyLine=1] - The 1-based file line the body starts on.
  * @param {number} [opts.bodyColumn=1] - The 1-based file column it starts at.
+ * @param {Array<{line: number, generated: boolean}>} [opts.lineMap] - From
+ *   table expansion, mapping each line of `body` back to the line an author
+ *   wrote, for a caller handing in a body whose tables already expanded.
  * @param {object} [opts.config] - The resolved build configuration. Supplied,
  *   an address is also held to the one surface a pathname can be dead on
  *   without any other pass noticing — see the Foundry address below. Omitted,
@@ -423,7 +507,7 @@ export function imageSourcesIn(body) {
  *   severity: "error", message: string}>} One finding per defect, in source
  *   order.
  */
-export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config } = {}) {
+export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, lineMap, config } = {}) {
     const text = String(body ?? "");
     if (!text) return [];
 
@@ -434,7 +518,7 @@ export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config }
      * @param {string} message - What is wrong.
      */
     const report = (offset, message) => {
-        const { line, column } = positionInBody(text, offset, { bodyLine, bodyColumn });
+        const { line, column } = positionInBody(text, offset, { bodyLine, bodyColumn, lineMap });
         findings.push({ file, line, column, severity: /** @type {"error"} */ ("error"), message });
     };
 
@@ -454,7 +538,7 @@ export function checkImages(body, file, { bodyLine = 1, bodyColumn = 1, config }
             report(
                 image.index,
                 `\`"${image.title}"\` is a title on an image, and no surface here draws ` +
-                    "one — an image's alt text is its caption",
+                    "one — a caption is written in a `:::figure` fence's /// section",
             );
         }
         if (!image.block) {
@@ -587,9 +671,13 @@ export function lintContentImages(contentBase, { skipDirectories = [], config }
  * @param {(src: string) => string} [resolveSrc] - Translates an authored
  *   pathname into the address this surface serves. The default is the identity,
  *   for a caller rendering the format rather than publishing it.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` translates it. The default answers nothing,
+ *   which is what an address resolving to no asset record gets anyway.
  * @returns {string} The same body, with each block image as a `<figure>`.
  */
-export function renderImageFigures(body, resolveSrc = (src) => src) {
+export function renderImageFigures(body, resolveSrc = (src) => src, lookupAsset = () => undefined) {
     const text = String(body ?? "");
     let out = "";
     let last = 0;
@@ -598,12 +686,16 @@ export function renderImageFigures(body, resolveSrc = (src) => src) {
         const { classes, size, float, problems } = parseImageDirective(image.directive);
         if (problems.length) continue;
         out += text.slice(last, image.index);
+        const asset = lookupAsset(image.src);
         out += imageFigureHtml({
             src: resolveSrc(image.src),
             alt: image.alt,
             classes,
             size,
             float,
+            role: asset?.role,
+            width: asset?.width,
+            height: asset?.height,
         });
         last = image.index + image.length;
     }
@@ -632,9 +724,13 @@ export function renderImageFigures(body, resolveSrc = (src) => src) {
  *   address into the one this surface serves. Foundry is handed the path inside
  *   the install; a renderer that resolves the address itself — the book stages
  *   its own copy — passes nothing and gets the address as authored.
+ * @param {(src: string) => {type?: string, role?: string, width?: number|"", height?: number|""}|undefined}
+ *   [lookupAsset] - What the resolved asset record says about the address, as
+ *   authored — before `resolveSrc` runs. The default answers nothing, which is
+ *   what an address resolving to no asset record gets anyway.
  * @returns {(md: object) => void} A markdown-it plugin.
  */
-export function imagePlugin(resolveSrc = (src) => src) {
+export function imagePlugin(resolveSrc = (src) => src, lookupAsset = () => undefined) {
     return (md) => {
         /** @type {any} */ (md).core.ruler.push("heroiclands_image", (state) => {
             attachImageDirectives(state.tokens);
@@ -649,12 +745,17 @@ export function imagePlugin(resolveSrc = (src) => src) {
         ) => {
             const token = tokens[idx];
             if (!token.meta?.block) return base(tokens, idx, options, env, self);
+            const src = token.attrGet("src") ?? "";
+            const asset = lookupAsset(src);
             return `${imageFigureHtml({
-                src: resolveSrc(token.attrGet("src") ?? ""),
+                src: resolveSrc(src),
                 alt: token.content ?? "",
                 classes: token.meta.classes,
                 size: token.meta.size,
                 float: token.meta.float,
+                role: asset?.role,
+                width: asset?.width,
+                height: asset?.height,
             })}\n`;
         };
     };

package/engine/content-index.mjs

@@ -32,8 +32,8 @@
  * over 15 types, from 9 on a `macro` to 72 on a `being`, and adding a field to
  * one type is ordinary authoring. Any format that fixes a column set would turn
  * that authoring into a schema migration, so nothing here selects, flattens, or
- * renames — a reader addresses `sohl.body.weight.base` because that is what the
- * note says, which a SQL query can address directly.
+ * renames — a reader addresses `sohl.system.body.weight.base` because that is
+ * what the note says, which a SQL query can address directly.
  *
  * **JSON Lines rather than a database.** The artifact has to survive its build
  * and be usable by anything — a person with `jq`, an editor, a CI check,
@@ -104,6 +104,8 @@ import { checkForeignAssetBindings } from "./asset-bindings.mjs";
 import { addressSlug, canonicalKey } from "./content-address.mjs";
 import { ownDocumentSystem } from "./address.mjs";
 import { NOTE_SYSTEM } from "./systems.mjs";
+import { assetAddressIndex } from "./art-fields.mjs";
+import { embedRole } from "./content-embeds.mjs";
 // One reader for a note's anchors, shared with the link checker and with the
 // builds that emit a link. Re-exported because this is where callers
 // have always addressed it.
@@ -443,6 +445,10 @@ function assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage) {
  *   entries are derived against.
  * @param {object} [options.addressContext] - Address resolution context.
  * @param {object} [options.dateContext] - Calendar conversion context.
+ * @param {(address: string) => string|undefined} [options.resolveRole] - From
+ *   a picture's address to the role its asset declares, so a figure anchor's
+ *   `name` reads `Map 1` rather than `Figure 1` where it is due — see
+ *   {@link module:engine/content-figures.scanFigures}.
  * @returns {Record<string, any>} The record, keys sorted at every depth. A
  *   **stub** — a note with an empty body, on a type an empty body suppresses —
  *   carries `address` and `anchors` as `null`: it publishes no page, so it
@@ -464,6 +470,7 @@ export function buildIndexRecord({
     manifest,
     addressContext,
     dateContext,
+    resolveRole,
 }) {
     assertNoDerivedKeys(frontmatter, relPath, absPath, contentPackage);
 
@@ -514,7 +521,7 @@ export function buildIndexRecord({
                 // there rather than search for the heading.
                 anchors:
                     stub ? null : (
-                        collectAnchors(body, bodyLine).map((a) => ({
+                        collectAnchors(body, bodyLine, resolveRole).map((a) => ({
                             ...a,
                             link: address ? `${address.slug}#${a.slug}` : null,
                         }))
@@ -615,6 +622,7 @@ export function indexRecordsForNote({
     manifest,
     addressContext,
     dateContext,
+    resolveRole,
 }) {
     resolveNoteId(frontmatter, { pkg: contentPackage });
     const record = buildIndexRecord({
@@ -627,6 +635,7 @@ export function indexRecordsForNote({
         manifest,
         addressContext,
         dateContext,
+        resolveRole,
     });
     const records = [decodeIndexAddresses(record, addressContext ?? { package: contentPackage })];
     const address = noteAddress(frontmatter, contentPackage);
@@ -726,7 +735,24 @@ export function collectContentIndex(
     // this same walk states one — the whole tree is already in memory, so no
     // second read is needed to answer a question about all of it.
     const present = presentAmongFrontmatters(parsedNotes.map((n) => n.frontmatter));
-    const dates = reckoningContext({ notes: parsedNotes.map((n) => n.frontmatter) });
+    // Carried on the same context `resolvedDateFields` reads: a recurring
+    // event's `next` is computed against this present exactly as a being's
+    // `age` already is, above.
+    const dates = {
+        ...reckoningContext({ notes: parsedNotes.map((n) => n.frontmatter) }),
+        present,
+    };
+
+    // Walked ahead of the notes, rather than after them as the records
+    // themselves are emitted: a note's anchors are collected below, and a
+    // figure fence's `map` counter needs this package's own asset roles
+    // before the first note is read, the same precedent the book's own
+    // cross-file numbering sets. A package with no `assetsBase` resolves no
+    // role, which is the one it would have resolved anyway.
+    const assetRecords =
+        assetsBase ? collectAssetRecords(assetsBase, { contentPackage, problems }) : [];
+    const assetIndex = assetAddressIndex(assetRecords, { config: { contentPackage } });
+    const resolveRole = (address) => embedRole(assetIndex, address);
 
     for (const { frontmatter, body, bodyLine, absPath } of parsedNotes) {
         const fm = frontmatter ?? {};
@@ -744,6 +770,7 @@ export function collectContentIndex(
                     manifest,
                     addressContext,
                     dateContext: dates,
+                    resolveRole,
                 }),
             );
         } catch (err) {
@@ -776,14 +803,13 @@ export function collectContentIndex(
         }
     }
 
-    if (assetsBase) {
-        // Sorted at every depth like a note's record, and for the same reason:
-        // the declaration order of the `asset` fields is a fact about the
-        // emitter, not about the content, and the artifact is meant to be
-        // byte-identical across two runs over an unchanged tree.
-        for (const record of collectAssetRecords(assetsBase, { contentPackage, problems })) {
-            records.push(/** @type {Record<string, any>} */ (sortKeysDeep(record)));
-        }
+    // Sorted at every depth like a note's record, and for the same reason: the
+    // declaration order of the `asset` fields is a fact about the emitter, not
+    // about the content, and the artifact is meant to be byte-identical across
+    // two runs over an unchanged tree. Collected above, ahead of the notes —
+    // see `resolveRole` — rather than walked a second time here.
+    for (const record of assetRecords) {
+        records.push(/** @type {Record<string, any>} */ (sortKeysDeep(record)));
     }
 
     // Source path, then the canonical address, then the note id. The walk

package/engine/content-links.mjs

@@ -302,24 +302,25 @@ export function buildLinkIndex(
     };
 
     /**
-     * One note's body with its SQL tables expanded.
+     * One note's body with its SQL tables and page lists expanded.
      *
      * The body every body-level check reads, so a link and an embed in one note
-     * are found in the same text — a generated table is as free to carry either
-     * as prose is.
+     * are found in the same text — a generated table or list is as free to
+     * carry either as prose is.
      *
      * @param {object} note - A note from this index.
      * @returns {string} The markdown.
      */
     function expandedBody(note) {
         const body = note.body;
-        if (!/^[ \t]*(?:`{3,}|~{3,})[ \t]*sql\b/im.test(body)) return body;
+        if (!/^[ \t]*(?:`{3,}|~{3,})[ \t]*(?:sql|pagelist)\b/im.test(body)) return body;
         return expandContentTables(body, {
             source: note.file,
-            // A `sql` table's links are checked like an authored one's, so
-            // its rows are prepared ahead of this walk — see
+            // A generated link is checked like an authored one, so both
+            // directives are prepared ahead of this walk — see
             // {@link module:engine/sql-tables.prepareTreeSqlTables}.
             sqlTables: sqlTables?.get(note.file),
+            pageLists: sqlTables?.pageLists?.get(note.file),
         }).markdown;
     }
 
@@ -954,6 +955,13 @@ export function auditLinks(index) {
                 deadAnchors.push({
                     note,
                     link: `${rawTarget}#${anchor}`,
+                    // The two the shared `unknown-anchor` wording reads, in the
+                    // same spelling the build's own pass gives them: the
+                    // address alone, and the slug the heading would have had to
+                    // declare. Carrying them is what lets one sentence serve
+                    // the checker and the build.
+                    target: rawTarget,
+                    anchor: slugify(anchor),
                     dest,
                     text,
                     occurrence,

package/engine/content-tables.mjs

@@ -1,21 +1,30 @@
 /* SPDX-License-Identifier: GPL-3.0-or-later */
 
 import { FENCE_LINE } from "./code-fences.mjs";
+import { PAGE_LIST_LANGUAGE } from "./page-lists.mjs";
 
 /**
- * Replace prepared SQL fences with Markdown tables while retaining source lines.
- * Query execution happens in the asynchronous SQL preparation pass.
+ * Replace prepared SQL fences and page lists with Markdown while retaining
+ * source lines.
+ *
+ * Both directives read the content index, so both are answered before this
+ * pass runs — query execution in the asynchronous SQL preparation pass, page
+ * lists in {@link module:engine/page-lists.preparePageLists} — and each is
+ * looked up by the ordinal of its own kind of fence within the body.
+ *
  * @param {string} markdown - The authored body.
- * @param {{source?: string, sqlTables?: object[]}} [context] - Prepared results.
+ * @param {{source?: string, sqlTables?: object[], pageLists?: object[]}} [context] -
+ *   Prepared results.
  * @returns {{markdown: string, errors: object[], warnings: object[], lineMap: object[]}}
  */
-export function expandContentTables(markdown, { source = "", sqlTables } = {}) {
+export function expandContentTables(markdown, { source = "", sqlTables, pageLists } = {}) {
     const lines = String(markdown ?? "").split("\n");
     const out = [];
     const lineMap = [];
     const errors = [];
     const warnings = [];
     let sqlOrdinal = 0;
+    let pageListOrdinal = 0;
     const emit = (value, line, generated = false) => {
         out.push(value);
         lineMap.push({ line, generated });
@@ -41,6 +50,38 @@ export function expandContentTables(markdown, { source = "", sqlTables } = {}) {
                 column: indent.length + 1,
             });
         }
+        if (language === PAGE_LIST_LANGUAGE) {
+            // The ordinal is consumed whether or not the fence was closed, so
+            // the two readings agree: `findPageListBlocks` records an unclosed
+            // directive as a directive with a problem rather than skipping it.
+            const prepared = pageLists?.[pageListOrdinal++];
+            const failure =
+                !prepared ? "page list was not prepared"
+                : prepared.reason ? prepared.reason
+                : prepared.pages === 0 && !prepared.allowEmpty ? prepared.empty
+                : undefined;
+            if (failure) {
+                errors.push({
+                    source,
+                    directive: block.join("\n"),
+                    reason: failure,
+                    line: i,
+                    column: indent.length + 1,
+                });
+                block.forEach((value, offset) => emit(value, i + offset));
+                i = close;
+                continue;
+            }
+            // A list the directive permitted to be empty leaves nothing
+            // behind, rather than a blank line where a list would have been.
+            if (prepared.markdown) {
+                if (out.length && out.at(-1).trim()) emit("", i, true);
+                for (const row of prepared.markdown.split("\n")) emit(`${indent}${row}`, i, true);
+                if (close + 1 < lines.length && lines[close + 1].trim()) emit("", i, true);
+            }
+            i = close;
+            continue;
+        }
         if (language !== "sql" || close >= lines.length) {
             block.forEach((value, offset) => emit(value, i + offset));
             i = close;