@heroiclands/package-build 22.15.0 → 22.16.0

package/engine/helpers.mjs

@@ -12,7 +12,7 @@
  */
 
 /**
- * Shared helpers for the pack compilers in `packages/content-build/`.
+ * Shared helpers for the pack compilers in `packages/package-build/`.
  *
  * The HeroicLands vault is authoritative for compendium item data. Pack
  * compilers walk the vault, read markdown files with YAML frontmatter, and
@@ -37,6 +37,8 @@ import path from "path";
 import yaml from "yaml";
 import unidecode from "unidecode";
 import markdownit from "markdown-it";
+import footnotePlugin from "markdown-it-footnote";
+import deflistPlugin from "markdown-it-deflist";
 import { iconPlugin } from "./content-icons.mjs";
 import { imagePlugin, imagesIn } from "./content-images.mjs";
 import { resolveEmbeds } from "./content-embeds.mjs";
@@ -46,7 +48,6 @@ import log from "loglevel";
 import { loadPackConfig } from "./pack-config.mjs";
 import { declaresNoPack, packRouter } from "./pack-router.mjs";
 import { contentPackage, foundryPackageId } from "./content-package.mjs";
-import { searchableFrontmatter } from "./note-package.mjs";
 import { PACKAGE_BASE } from "./content-address.mjs";
 import { resolveNoteId } from "./note-ids.mjs";
 import { loadForeignIndexes, noContentIndexPackages } from "./metadata-index.mjs";
@@ -61,8 +62,11 @@ import { linkFindingMessage } from "./wikilink-syntax.mjs";
 // The declared tag vocabulary, which is where `draft` is stated. Read
 // from there rather than respelt, so the tag and its one reader cannot drift.
 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 { 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
 // registry can import them without reaching back through this one.
@@ -88,6 +92,8 @@ export {
  * the two HTML surfaces and be silently dropped by the third.
  */
 export const md = markdownit({ html: true })
+    .use(footnotePlugin)
+    .use(deflistPlugin)
     .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
@@ -126,10 +132,35 @@ export const md = markdownit({ html: true })
         }),
     );
 
+md.renderer.rules.footnote_block_open = () =>
+    '<section class="footnotes"><h2>Footnotes</h2><ol class="footnotes-list">\n';
+md.renderer.rules.footnote_caption = (tokens, idx, _options, env) => {
+    const meta = tokens[idx].meta;
+    const number = env.footnoteNumbers?.get(meta.label) ?? meta.id + 1;
+    return `[${number}${meta.subId > 0 ? `:${meta.subId}` : ""}]`;
+};
+md.renderer.rules.footnote_anchor_name = (tokens, idx, _options, env) => {
+    const meta = tokens[idx].meta;
+    const number = env.footnoteNumbers?.get(meta.label) ?? meta.id + 1;
+    return `${env.docId ? `-${env.docId}-` : ""}${number}`;
+};
+md.renderer.rules.footnote_open = (tokens, idx, options, env, renderer) => {
+    const meta = tokens[idx].meta;
+    const number = env.footnoteNumbers?.get(meta.label) ?? meta.id + 1;
+    const id = renderer.rules.footnote_anchor_name(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. */
-export function renderFoundryMarkdown(body) {
+export function renderFoundryMarkdown(body, captions, footnoteNumbers, docId) {
     const { markdown } = renderSecretBlocks(body, "foundry", (inner) => md.render(inner));
-    return md.render(markdown);
+    const admonitions = renderAdmonitions(markdown, (inner) => md.render(inner));
+    const captioned = renderCaptionBlocks(
+        admonitions.markdown,
+        (block) => md.render(block),
+        captions,
+    );
+    return md.render(captioned.markdown, { footnoteNumbers, docId });
 }
 
 /**
@@ -143,6 +174,10 @@ export function renderFoundryMarkdown(body) {
  * {@link positionInBody}. If the file has no frontmatter block, returns
  * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
  * position: there is no body to have one.
+ * @param {string} filePath - Markdown file to read.
+ * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
+ * @returns {{frontmatter: object|null, body: string, description: string,
+ *   bodyLine?: number, bodyColumn?: number}} Parsed note and body position.
  */
 export function parseMarkdownFile(filePath, { addressContext } = {}) {
     const content = fs.readFileSync(filePath, "utf8");
@@ -257,6 +292,7 @@ export function assertSuppliedCorpus(records, who) {
  * @param {readonly string[]} opts.skipDirectories - Directory names to ignore.
  *   Required: the scope is the caller's to state, so two passes cannot
  *   disagree about which files are the corpus.
+ * @param {object} [opts.addressContext] - Address resolution context.
  * @yields {{frontmatter: object|null, body: string, description: string,
  *   file: string, absPath: string, bodyLine?: number, bodyColumn?: number}}
  *   One entry per `.md` file found.
@@ -470,6 +506,9 @@ export function systemTemplatePriority(fm, label) {
 /**
  * Generates a compendium-source filename: `Name_id.json` with non-
  * alphanumeric runs replaced by underscores.
+ * @param {string} name - Document name.
+ * @param {string} id - Document id.
+ * @returns {string} Filename for the document.
  */
 export function makeFilename(name, id) {
     return `${unidecode(name)}_${id}`.replace(/[^0-9a-zA-Z]+/g, "_") + ".json";
@@ -531,6 +570,9 @@ export function resolveImg(raw, config = loadPackConfig()) {
 /**
  * Resolves the display name from frontmatter, preferring `name.full`,
  * falling back to `name` (if string), then `defaultValue`.
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} [defaultValue] - Name when the note provides none.
+ * @returns {string} Display name.
  */
 export function resolveName(fm, defaultValue = "Unnamed") {
     const fullName = getFrontmatter(fm, "name.full", null);
@@ -707,20 +749,16 @@ import { collectAnchors } from "./anchors.mjs";
  *   the index and the compile agree about where each note landed; defaults to
  *   this repository's own.
  * @param {object} [opts]
- * @param {readonly string[]} [opts.skipDirectories] - Part of the options bag
- *   every corpus reader takes; the scope is already settled by `records`.
  * @param {object} [opts.config] - The resolved build configuration; loaded when
  *   omitted.
  * @param {readonly object[]} [opts.records] - The corpus, derived once per
  *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
- * @param {object[]} [opts.problems] - Part of the same options bag; the notes
- *   the index cannot record are collected where the corpus is derived.
  * @returns {{byShortcode: Map, types: Set}} From `buildWikilinkIndex`.
  */
 export function buildContentLinkIndex(
     contentBase,
     router = packRouter(),
-    { skipDirectories, config, records, problems } = {},
+    { config, records } = {},
 ) {
     const docs = [];
     /** The files this package ships, by canonical address. */
@@ -764,17 +802,21 @@ export function buildContentLinkIndex(
         assertTypeNotRetired(fm.type, absPath);
         const base = String(record.file.name).replace(/_/g, " ");
         const documentation = recordsByAddress.get(encodeAddresses(record.documentation));
+        const noOwnDocument =
+            declaresNoPack(fm) ||
+            NEVER_PACKED_TYPES.has(fm.type) ||
+            DERIVED_PACKED_TYPES.has(fm.type);
         docs.push({
             documentationUuid: documentation?.foundry?.none?.uuid ?? null,
             type: fm.type,
             id: fm.id,
             // Where this note's own document lands, and where the JournalEntry
             // its prose compiles into lands — two documents, two packs.
-            pack: router.resolveOrNull(fm, packForType(fm.type).docType),
-            docPack: router.resolveOrNull(fm, "JournalEntry"),
-            // Whether the note declares `pack: none` and so has no document
-            // at all: a link to it names a page, never a compendium entry.
-            none: declaresNoPack(fm),
+            pack: noOwnDocument ? null : router.resolveOrNull(fm, packForType(fm.type).docType),
+            docPack: noOwnDocument ? null : router.resolveOrNull(fm, "JournalEntry"),
+            // A note with no single document still has an address, but no
+            // compendium UUID for a wikilink to open.
+            none: noOwnDocument,
             shortcode: fm.shortcode ?? null,
             // What the note *is*, carried so a caller resolving a reference
             // can group by the family its target declares rather than only by
@@ -812,7 +854,7 @@ export function buildContentLinkIndex(
         }
         throw new Error(
             "Cross-package links cannot be resolved from an unusable index; " +
-                "re-run `content-build deps fetch`.",
+                "re-run `package-build deps fetch`.",
         );
     }
     log.debug(
@@ -883,6 +925,9 @@ export function convertNoteWikilinks(
         pack,
         docPack,
         index,
+        captionLabels: new Map(
+            scanCaptions(source).captions.map((caption) => [caption.id, caption.label]),
+        ),
     });
     /**
      * Where one unresolved link sits, in file coordinates.
@@ -973,115 +1018,21 @@ export function convertNoteWikilinks(
 /* ------------------------------------------------------------------------ */
 
 /**
- * Every note in the content tree, in the shape the `dataview` table expander
- * searches: its frontmatter plus where it sits in the tree. Ordered by path so
- * a table that leaves rows tied still emits identically on every build.
- *
- * @param {string} contentBase - Root of the content tree.
- * @param {object} [opts]
- * @param {readonly string[]} [opts.skipDirectories] - Part of the options bag
- *   every corpus reader takes; the scope is already settled by `records`.
- * @param {object} [opts.config] - The resolved build configuration; loaded when
- *   omitted.
- * @param {readonly object[]} [opts.records] - The corpus, derived once per
- *   compile and handed in. Required: see {@link assertSuppliedCorpus}.
- * @param {object[]} [opts.problems] - Part of the same options bag; the notes
- *   the walk cannot read are collected where the corpus is derived.
- * @returns {Array<{fm: object, path: string, tld: string, folder: string,
- *   absPath: string}>}
- */
-export function collectContentDocs(
-    contentBase,
-    { skipDirectories, config, records, problems } = {},
-) {
-    const docs = [];
-    const resolved = config ?? loadPackConfig();
-    assertSuppliedCorpus(records, "collectContentDocs");
-    for (const record of records) {
-        if (!isNoteRecord(record)) continue;
-        const fm = authoredFrontmatter(record);
-        const absPath = noteFile(contentBase, record);
-        const segments = String(record.file.path).split("/");
-        docs.push({
-            // With its package supplied for a `WHERE … package = "…"` query —
-            // synthesised from the configuration this build resolved, since no
-            // note declares it and the ambient one is a different
-            // configuration in a worktree or under `PACKAGE_BUILD_CONFIG`.
-            fm: searchableFrontmatter(fm, resolved.contentPackage),
-            // POSIX-separated and relative to the content root — what a
-            // `path:` search term globs, on every platform.
-            path: segments.join("/"),
-            tld: segments[0],
-            folder: segments[segments.length - 2] ?? segments[0],
-            absPath,
-        });
-    }
-    docs.sort((a, b) =>
-        a.absPath < b.absPath ? -1
-        : a.absPath > b.absPath ? 1
-        : 0,
-    );
-    log.debug(`Content table index: ${docs.length} searchable note(s)`);
-    return docs;
-}
-
-/**
- * A note is linkable from a generated table cell when it carries the identity
- * {@link convertWikilinks} addresses it by — a `type` and a `shortcode`. Every
- * type routes to a pack ({@link packForType}), so nothing else can make a note
- * unlinkable; a note missing either renders as plain text rather than shipping a
- * literal wikilink into a journal.
- */
-const packLinkable = (doc) => Boolean(doc.fm?.shortcode) && Boolean(doc.fm?.type);
-
-/**
- * Expand the fenced `dataview` tables in one note's markdown, before wikilinks
- * are resolved — so a generated cell may itself be a wikilink.
- *
- * A table searches the whole tree, which is one package's notes and nothing
- * else — so there is no longer a package to scope on. It used to filter, back
- * when a tree could hold several packages' notes and `package:` said which was
- * which; that field is retired and the filter with it.
- *
- * @param {string} body - The note's markdown body.
- * @param {object} ctx
- * @param {Array<object>} ctx.docs - From {@link collectContentDocs}.
- * @param {string} ctx.name - The note, for the error message.
- * @param {object} [ctx.fm] - The source note's frontmatter, which is what a
- *   query's `this` reads. Its entry in `docs` supplies the path as well.
- * @param {number} [ctx.bodyLine] - 1-based file line of the body's first line,
- *   so a failing directive can be reported at its position in the file.
- * @param {object[]} [ctx.sqlTables] - This note's prepared `sql` results, in
- *   document order, from
- *   {@link module:engine/sql-tables.prepareSqlTables}. An `sql` directive with
- *   no prepared result fails the note: nothing here runs a query.
- * @returns {{markdown: string, lineMap: Array<{line: number,
- *   generated: boolean}>}} The body with every table expanded, and where each
- *   emitted line came from — which is what lets a diagnostic about the
- *   expanded body name an authored position.
- * @throws {Error} When a query is malformed or unsupported — the note fails to
- *   compile rather than shipping a table-shaped hole. The error carries
- *   `position`, the directive's own line.
+ * Expand prepared SQL tables before resolving wikilinks in generated cells.
+ * @param {string} body - The note body.
+ * @param {object} ctx - Source and prepared query 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.
+ * @returns {{markdown: string, lineMap: Array<{line: number, generated: boolean}>}}
  */
-export function expandNoteTables(body, { docs, name, fm, bodyLine, sqlTables }) {
-    const self =
-        fm ?
-            (docs.find((d) => d.fm?.id && d.fm.id === fm.id) ?? {
-                fm: searchableFrontmatter(fm),
-            })
-        :   undefined;
+export function expandNoteTables(body, { name, bodyLine, sqlTables }) {
     const { markdown, errors, lineMap } = expandContentTables(body ?? "", {
-        docs,
-        linkable: packLinkable,
         source: name,
-        self,
         sqlTables,
     });
     if (errors.length) {
         const err = new Error(errors.map((e) => `content table — ${e.reason}`).join("; "));
-        // The first failing directive's line. Reporting one position for a
-        // message that may name several is honest here: a caller opens the
-        // file at the first thing to fix, and the message lists the rest.
         if (bodyLine !== undefined && errors[0].line !== undefined) {
             err.position = { line: bodyLine + errors[0].line };
         }
@@ -1098,6 +1049,9 @@ export function expandNoteTables(body, { docs, name, fm, bodyLine, sqlTables })
  * Builds a compendium-source filename for a folder JSON document:
  * `folder_Name_id.json` with non-alphanumeric runs replaced by
  * underscores.
+ * @param {string} name - Folder name.
+ * @param {string} id - Folder id.
+ * @returns {string} Filename for the folder.
  */
 export function folderFilename(name, id) {
     return `folder_${unidecode(name)}_${id}`.replace(/[^0-9a-zA-Z]+/g, "_") + ".json";

package/engine/homepage.mjs

@@ -264,9 +264,8 @@ export function checkHomepageAddressFields(fm, { isAuthored } = {}) {
  * {@link module:engine/diagnostics}. {@link lintContentTree} already reports an
  * empty walk against the same locator.
  *
- * The rule reads no `site:` configuration and does not vary by
- * `publish.site`: that setting chooses whether the *content* surfaces are
- * published, and the homepage is the floor underneath both modes.
+ * The rule applies to every content tree, whether it contains only the
+ * homepage or other notes as well.
  *
  * @param {ReadonlyArray<{file: string}>} found - The homepage notes, in walk
  *   order. Paths may be absolute or relative to the working directory.

package/engine/index-records.mjs

@@ -61,6 +61,7 @@ export const DERIVED_KEYS = Object.freeze([
     "documentation",
     "documents",
     "asset",
+    "resolvedDates",
 ]);
 
 /**

package/engine/index.mjs

@@ -42,6 +42,9 @@ export * as systemBlock from "./system-block.mjs";
 /** Fenced-code detection, so a rewrite never edits a code block. */
 export * as codeFences from "./code-fences.mjs";
 
+/** Format generated text using the destination's Prettier configuration. */
+export { formatGenerated } from "./format-generated.mjs";
+
 /** The `sohl:` frontmatter readers, shared by every content package. */
 export * as frontmatter from "./frontmatter.mjs";
 
@@ -109,13 +112,13 @@ export * as mapPlaces from "./map-places.mjs";
 /** The geometry of the map from a place: bearings to angles, days to rings, hops composed. */
 export * as mapLayout from "./map-layout.mjs";
 
-/** The three drawings of `content-build map`, as DOT. */
+/** The three drawings of `package-build map`, as DOT. */
 export * as mapDot from "./map-dot.mjs";
 
 /** GraphViz, as the map command finds and runs it. */
 export * as mapGraphviz from "./map-graphviz.mjs";
 
-/** `content-build map`: the drawings, written under `build/map/`. */
+/** `package-build map`: the drawings, written under `build/map/`. */
 export * as mapBuild from "./map-build.mjs";
 
 /** The map from each place, drawn for the site and written into its page. */
@@ -130,6 +133,18 @@ export * as calendars from "./calendars.mjs";
 /** A note's dates: one authored string, one grammar, one record shape. */
 export * as noteDates from "./note-dates.mjs";
 
+/** Exact day conversion between an authored calendar and the canonical axis. */
+export * as dateConversion from "./date-conversion.mjs";
+
+/** Inline frontmatter and date expressions in Markdown prose. */
+export * as markdownExpressions from "./markdown-expressions.mjs";
+
+/** A being's or place's chosen calendar note. */
+export * as calendarChoice from "./calendar-choice.mjs";
+
+/** A being's primary culture Address, checked against lore subtype. */
+export * as cultureChoice from "./culture-choice.mjs";
+
 /** Era markers resolved from calendar notes in a corpus. */
 export * as reckoningMarkers from "./reckoning-markers.mjs";
 
@@ -220,7 +235,7 @@ export * as contentLinks from "./content-links.mjs";
 /** Wikilinks resolved to a **web URL** — the site half of the pair below. */
 export * as webWikilinks from "./web-wikilinks.mjs";
 
-/** Dataview-style content tables, expanded into markdown at compile time. */
+/** Prepared SQL content tables, expanded into Markdown at compile time. */
 export * as contentTables from "./content-tables.mjs";
 
 /** Markdown parsing, stats, folders, images, and the wikilink index. */

package/engine/infobox-registry.mjs

@@ -111,17 +111,19 @@ export function compilesSystemDocument(fm, map, router) {
  *   Resolves a reference to `{name, url?, uuid?, address?, subType?}`.
  * @param {object} [options.router] - The pack router deciding which system
  *   compiles a document for this note. Defaults to the consuming repository's.
+ * @param {object} [options.dates] - Calendar conversion context.
  * @returns {object[]} The boxes, in the order every medium renders them.
  * @throws {Error} When the built set disagrees with what the note's type maps
  *   to — see {@link module:engine/infobox.assertInfoboxSet}.
  */
-export function noteInfoboxes(fm, { resolve, router = packRouter() } = {}) {
+export function noteInfoboxes(fm, { resolve, router = packRouter(), dates } = {}) {
     const boxes = buildInfoboxes(fm, {
         maps: KNOWN_DOCUMENT_SUBTYPE_MAPS,
         providers: KNOWN_INFOBOXES,
         compilesDocument: (note, map) => compilesSystemDocument(note, map, router),
         resolveField: resolveFieldValue,
         resolve,
+        dates,
     });
     return /** @type {object[]} */ (
         assertInfoboxSet(boxes, fm, { maps: KNOWN_DOCUMENT_SUBTYPE_MAPS })

package/engine/infobox.mjs

@@ -119,6 +119,8 @@ import { NOTE_VOCABULARY, dataFields } from "./note-vocabulary.mjs";
 import { readAliasedField } from "./retired-fields.mjs";
 import { subtypeRow } from "./document-subtypes.mjs";
 import { authoredKey } from "./system-block.mjs";
+import { formatDateInCalendar, formatNoteDate, parseNoteDate } from "./note-dates.mjs";
+import { displayBeingHeight, displayBeingWeight } from "./being-measurements.mjs";
 
 /**
  * How a section arranges what it holds.
@@ -300,8 +302,8 @@ export const NOTE_FIELD_PRESENTATION = Object.freeze({
     "being.ageYears": Object.freeze({
         withheld: "the `age` row's own machinery, not a second fact about the subject",
     }),
-    "being.height": Object.freeze({ group: "appearance", phrase: heightPhrase }),
-    "being.weight": Object.freeze({ group: "appearance", phrase: weightPhrase }),
+    "being.height": Object.freeze({ group: "appearance", phrase: displayBeingHeight }),
+    "being.weight": Object.freeze({ group: "appearance", phrase: displayBeingWeight }),
     "being.frame": Object.freeze({ group: "appearance", phrase: (v) => `${v} frame` }),
     "being.appearance.eye_color": Object.freeze({
         group: "appearance",
@@ -348,18 +350,6 @@ export function overlayFor(presentation, type, name) {
 /** What a composed group's row is called. @type {Readonly<Record<string, string>>} */
 const GROUP_LABELS = Object.freeze({ appearance: "Appearance" });
 
-/** Metres as feet and inches, which is how the corpus reads a height. */
-function heightPhrase(metres) {
-    const inches = Math.round(Number(metres) * 39.3701);
-    const feet = Math.floor(inches / 12);
-    return `${feet}′ ${inches - feet * 12}″`;
-}
-
-/** Kilograms as pounds, which is how the corpus reads a weight. */
-function weightPhrase(kilograms) {
-    return `${Math.round(Number(kilograms) * 2.20462)} lbs`;
-}
-
 /** Whether a value is a plain mapping. */
 function isMapping(value) {
     return Boolean(value) && typeof value === "object" && !Array.isArray(value);
@@ -701,7 +691,7 @@ export function noteInfobox(fm, options = {}) {
  */
 function noteBox(
     fm,
-    { resolve, vocabulary = NOTE_VOCABULARY, presentation = NOTE_FIELD_PRESENTATION } = {},
+    { resolve, dates, vocabulary = NOTE_VOCABULARY, presentation = NOTE_FIELD_PRESENTATION } = {},
 ) {
     const rows = [];
     /** @type {Set<string>} */
@@ -721,7 +711,34 @@ function noteBox(
         // The current name wins, which is the whole of the retirement window's
         // behaviour and is `readAliasedField`'s answer, not a second one.
         const own = getFrontmatter(data, field.name, undefined);
-        const raw = own !== undefined ? own : readAliasedField(fm, field.name, { inData: true });
+        let raw = own !== undefined ? own : readAliasedField(fm, field.name, { inData: true });
+        if (
+            ((fm?.type === "being" && ["born", "died"].includes(field.name)) ||
+                (fm?.type === "place" && field.name === "present")) &&
+            dates
+        ) {
+            const parsed = parseNoteDate(raw, dates).date;
+            const era =
+                parsed?.marker ? dates.markers?.get(parsed.marker)
+                : parsed?.qualifier ? dates.eras?.get(parsed.qualifier)
+                : null;
+            let printable = null;
+            if (parsed?.known && data.calendar) {
+                try {
+                    printable = formatDateInCalendar(
+                        parsed,
+                        isAddressTuple(data.calendar) ?
+                            renderAddress(data.calendar)
+                        :   data.calendar,
+                        dates,
+                    );
+                } catch {
+                    // The calendar reference is checked at the authored field.
+                }
+            }
+            printable ??= formatNoteDate(parsed, era, dates.daysPerYear);
+            if (printable) raw = printable.prose ?? printable.text;
+        }
         const structured = structuredRows(
             field,
             raw,
@@ -889,7 +906,7 @@ export function isDeclaredDefault(field, raw) {
  *
  * @param {object} fm - The note's frontmatter.
  * @param {readonly object[]} fields - The system's field declaration.
- * @param {object} ctx - `{ block, resolve, resolveField, taken, presentation }`.
+ * @param {{block: string, resolve?: Function, resolveField?: Function, taken?: Set<string>, presentation?: object}} ctx - Rendering context.
  * @returns {object[]} Zero or one section.
  */
 export function systemRowsSection(
@@ -956,9 +973,10 @@ export function buildInfoboxes(fm, options) {
         resolveField,
         resolve,
         vocabulary = NOTE_VOCABULARY,
+        dates,
     } = options;
 
-    const { box: note, shown: taken } = noteBox(fm, { resolve, vocabulary });
+    const { box: note, shown: taken } = noteBox(fm, { resolve, vocabulary, dates });
     const boxes = [note];
 
     for (const map of maps ?? []) {
@@ -1017,7 +1035,7 @@ export function sectionHolds(section) {
  * against a restatement of it.
  *
  * @param {object} fm - The note's frontmatter.
- * @param {object} options - `{ maps }`.
+ * @param {{maps: readonly object[]}} options - Document subtype mappings.
  * @returns {string[]} The ids.
  */
 export function requiredInfoboxIds(fm, { maps }) {
@@ -1040,7 +1058,7 @@ export function requiredInfoboxIds(fm, { maps }) {
  *
  * @param {readonly object[]} boxes - What was built.
  * @param {object} fm - The note's frontmatter.
- * @param {object} options - `{ maps, where }`.
+ * @param {{maps: readonly object[], where?: string}} options - Document subtype mappings and context.
  * @returns {readonly object[]} The boxes, unchanged, so a caller may assert
  *   inline.
  * @throws {Error} Naming the note, what is missing and what is extra.

package/engine/item-compiler.mjs

@@ -50,7 +50,7 @@ import log from "loglevel";
 
 import { resolveName } from "./helpers.mjs";
 import { BasePackCompiler } from "./base-compiler.mjs";
-import { journalPageId, splitPages } from "./journals.mjs";
+import { assertUniquePages, journalPageId, splitPages } from "./journals.mjs";
 import { foundryPackageId } from "./content-package.mjs";
 import { itemDocEntryId, itemDocPointer } from "./item-docs.mjs";
 // The whitelist and the per-type `system` builders both come from the resolved
@@ -76,15 +76,15 @@ import { assertNoDerivedFields } from "./derived-fields.mjs";
 import { assertNoRuntimeOnlyFields } from "./runtime-only-fields.mjs";
 
 /**
- * The description an item carries: a pointer to its **item doc**, the
- * JournalEntry the journals pass compiles this same body into.
+ * The description an item carries: a pointer to a page of its **item doc**,
+ * the JournalEntry the journals pass compiles this same body into.
  *
  * The prose is not rendered into the item at all. Carrying it would duplicate
  * it onto every actor holding the item — 7.59 MB of copies across the actors
  * pack, of which 133 KB was distinct — where a link is 60 bytes and always
  * current. The two passes derive the target from the note's own id, so neither
- * has to see the other's output; both split the *converted* markdown, so an H1
- * carrying a wikilink names the same page on both sides.
+ * has to see the other's output. `{#description}` selects the named page;
+ * an item without that anchor points to its first page.
  *
  * An item with no prose points at nothing, exactly as the journals pass writes
  * no entry for it.
@@ -97,9 +97,11 @@ import { assertNoRuntimeOnlyFields } from "./runtime-only-fields.mjs";
  */
 export function itemDescription(markdown, fm, name) {
     if (!String(markdown).trim()) return "";
-    const [leadPage] = splitPages(markdown, name);
-    const pageId = journalPageId(itemDocEntryId(fm.id), leadPage);
-    return itemDocPointer(foundryPackageId(), fm.id, name, pageId);
+    const pages = splitPages(markdown, name);
+    assertUniquePages(pages, name);
+    const page = pages.find((entry) => entry.anchorSlug === "description") ?? pages[0];
+    const pageId = journalPageId(itemDocEntryId(fm.id), page);
+    return itemDocPointer(foundryPackageId(), fm.id, name, pageId, fm);
 }
 
 /**

package/engine/item-docs.mjs

@@ -18,7 +18,7 @@
  * An item note's body describes what the thing *is*. That is documentation, and
  * documentation belongs in the journals pack, so each item note compiles into a
  * JournalEntry and the item's `system.docHtml` becomes nothing but a `@UUID`
- * link to that entry's first page — the description-as-pointer convention,
+ * link to its `{#description}` page, or its first page when that anchor is absent — the description-as-pointer convention,
  * which {@link sohl.utils.descriptionLinkTarget} recognises and
  * Display Description follows.
  *
@@ -92,7 +92,7 @@ export function itemDocEntryId(itemId) {
 
 /**
  * The description an item carries in place of its prose: a `@UUID` link to the
- * first page of its item doc, and nothing else.
+ * description page of its item doc, and nothing else.
  *
  * "Nothing else" is the whole convention — a description that is *only* a link
  * is a pointer, and anything alongside it would make it ordinary prose that
@@ -104,18 +104,19 @@ export function itemDocEntryId(itemId) {
  * @param {string} name - The item's name, used as the link's label. It shows
  *   only if the target ever fails to resolve, where a broken link naming the
  *   item beats a bare UUID.
- * @param {string} firstPageId - The id of the entry's first page, from
+ * @param {string} pageId - The id of the selected entry page, from
  *   {@link journalPageId}.
+ * @param {object} [fm] - The source note, used to route GM-only prose.
  * @returns {string} The pointer to store in `system.docHtml`.
  */
-export function itemDocPointer(packageId, itemId, name, firstPageId) {
+export function itemDocPointer(packageId, itemId, name, pageId, fm) {
     // An item doc is a *derived* document: it lands in the default
     // JournalEntry pack whatever Item pack the item itself was routed to.
     const entryUuid = compendiumUuid(
         packageId,
         "doc",
         itemDocEntryId(itemId),
-        packRouter().defaultOf("JournalEntry"),
+        fm ? packRouter().resolve(fm, "JournalEntry") : packRouter().defaultOf("JournalEntry"),
     );
-    return `@UUID[${pageUuid(entryUuid, firstPageId)}]{${name}}`;
+    return `@UUID[${pageUuid(entryUuid, pageId)}]{${name}}`;
 }

package/engine/itinerary-scenes.mjs

@@ -6,6 +6,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
+import { resolvePackageBuildConfig } from "../config.mjs";
 
 import { buildMaps, relatedPlaces } from "./map-build.mjs";
 import { renderDot } from "./map-graphviz.mjs";
@@ -74,6 +75,7 @@ export function buildItineraryScenes({
     stats,
     foreign = loadForeignIndexes(config, [config.contentPackage]),
 }) {
+    const buildConfig = resolvePackageBuildConfig(config);
     const world = mapWorld({ records, foreignIndex: foreign.index, contentBase, config });
     const centres = relatedPlaces(world.places).filter((sc) => world.places.get(sc)?.local);
     const findings = foreign.stale.map((stale) => ({
@@ -83,7 +85,7 @@ export function buildItineraryScenes({
     }));
     const assetDir = path.resolve(
         config.rootDir,
-        config.packageBuild.stageDir,
+        buildConfig.stageDir,
         "assets/maps/generated-itineraries",
     );
     fs.rmSync(assetDir, { recursive: true, force: true });
@@ -112,7 +114,7 @@ export function buildItineraryScenes({
         const [width, height] = pngDimensions(png);
         const positions = pinPositions(fs.readFileSync(plain, "utf8"), width, height);
         const sceneId = makeId("itinerary-scene", `${config.contentPackage}:${centre}`);
-        const src = `${config.packageKind}/${config.foundryPackage.id}/assets/maps/generated-itineraries/from-${centre}.png`;
+        const src = `${buildConfig.packageKind}/${buildConfig.packageId}/assets/maps/generated-itineraries/from-${centre}.png`;
         const scene = buildScene(
             {
                 id: sceneId,