@heroiclands/package-build 23.7.0 → 23.8.0

package/engine/language-words.mjs

@@ -28,6 +28,10 @@
  * - no form stands twice in one language;
  * - a word's `gloss` states at least one sense;
  * - an affix that `replaces` the stem's close does not also `lengthen` it;
+ * - an affix states `given` only where its `kind` is `name`;
+ * - an affix states a `form` or `zero: true`, never both;
+ * - an element's `word` and the particle of `data.negation` are forms of the
+ *   words of the language or an ancestor;
  * - a word's `frame` names a frame of `data.sounds.frames`, its language's or
  *   an ancestor's;
  * - every source language resolves, and names a language skill;
@@ -51,6 +55,7 @@ import { addressKeyOf, ownKey } from "./culture-reach.mjs";
 import {
     BORROWED_SOURCE_KIND,
     LANGUAGE_SUBTYPE,
+    NAME_AFFIX_KIND,
     WORD_DATA_KEYS,
     glossSenses,
     pronunciationProblem,
@@ -287,6 +292,76 @@ export function checkLanguageWords(note, { index } = {}) {
         });
     });
 
+    listOf(data.affixes).forEach((affix, i) => {
+        if (!isMap(affix)) return;
+        const form = typeof affix.form === "string" && affix.form.trim() !== "";
+        const zero = affix.zero === true;
+        if (form && zero)
+            findings.push(
+                finding(
+                    ["data", "affixes", i, "zero"],
+                    "error",
+                    `\`data.affixes[${i}]\` states a \`form\` and \`zero: true\`; a zero affix states no form`,
+                    true,
+                ),
+            );
+        else if (!form && !zero && affix.form == null)
+            findings.push(
+                finding(
+                    ["data", "affixes", i],
+                    "error",
+                    `\`data.affixes[${i}]\` states neither a \`form\` nor \`zero: true\``,
+                ),
+            );
+    });
+
+    listOf(data.affixes).forEach((affix, i) => {
+        if (!isMap(affix) || affix.given == null || affix.kind === NAME_AFFIX_KIND) return;
+        findings.push(
+            finding(
+                ["data", "affixes", i, "given"],
+                "error",
+                "`given` says who a given name belongs to, and " +
+                    (typeof affix.kind === "string" ?
+                        `\`data.affixes[${i}]\` is of kind \`${affix.kind}\``
+                    :   `\`data.affixes[${i}]\` is of no kind`) +
+                    `; it is stated on an affix of kind \`${NAME_AFFIX_KIND}\` only`,
+                true,
+            ),
+        );
+    });
+
+    // The forms an element's `word` and the negative particle may name.
+    const wordForms = new Set();
+    for (const one of [data, ...ancestors])
+        for (const word of listOf(one?.words))
+            if (isMap(word) && typeof word.form === "string") wordForms.add(word.form);
+    listOf(data.elements).forEach((element, i) => {
+        if (!isMap(element) || typeof element.word !== "string" || wordForms.has(element.word))
+            return;
+        findings.push(
+            finding(
+                ["data", "elements", i, "word"],
+                "error",
+                `the word \`${element.word}\` of the element \`${element.form}\` is not a form of ` +
+                    "this language's words or its ancestors'",
+            ),
+        );
+    });
+    if (
+        isMap(data.negation) &&
+        typeof data.negation.particle === "string" &&
+        !wordForms.has(data.negation.particle)
+    )
+        findings.push(
+            finding(
+                ["data", "negation", "particle"],
+                "error",
+                `the negative particle \`${data.negation.particle}\` is not a form of this ` +
+                    "language's words or its ancestors'",
+            ),
+        );
+
     listOf(data.affixes).forEach((affix, i) => {
         if (!isMap(affix) || affix.lengthens !== true || affix.replaces == null) return;
         findings.push(

package/engine/markdownlint-run.mjs

@@ -41,6 +41,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
+import { markupFindings } from "./markup-validation.mjs";
 
 import ignore from "ignore";
 import {
@@ -447,8 +448,9 @@ function gitignoreHooks(root) {
  *   `config`, `ignores`, `gitignore` and `globs`.
  * @param {boolean} [params.fix=false] - Repair what markdownlint can, then
  *   report what remains.
- * @returns {Promise<{results: object[]}>} markdownlint results, each with its
+ * @returns {Promise<{results: object[], markup: object[]}>} markdownlint results, each with its
  *   `fileName` relative to `directory`, ordered by file, line and rule.
+ *   `markup` carries block syntax diagnostics with absolute filenames.
  * @throws {MarkdownConfigError} A configuration file the contract refuses.
  */
 export async function runMarkdownlint(params) {
@@ -530,12 +532,20 @@ export async function runMarkdownlint(params) {
     };
 
     const resultsByFile = new Map();
+    const markup = [];
     for (const [dir, files] of groups) {
         const options = await lintOptions(dir, files);
+        const malformed = new Set();
+        for (const file of files) {
+            const findings = markupFindings(fs.readFileSync(file, "utf8"), file);
+            if (findings.length) malformed.add(file);
+            markup.push(...findings);
+        }
         let results = await lint(options);
         if (fix) {
             const toFix = [];
             for (const file of files) {
+                if (malformed.has(file)) continue;
                 const fixable = (results[file] ?? []).filter((error) => error.fixInfo);
                 if (!fixable.length) continue;
                 const original = fs.readFileSync(file, "utf8");
@@ -563,5 +573,5 @@ export async function runMarkdownlint(params) {
             a.ruleNames[0].localeCompare(b.ruleNames[0]) ||
             order.get(a) - order.get(b),
     );
-    return { results: flat };
+    return { results: flat, markup };
 }

package/engine/markup-validation.mjs

@@ -0,0 +1,34 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { scanBlocks } from "./content-blocks.mjs";
+import { scanAlerts } from "./content-alerts.mjs";
+
+/**
+ * Validate authored block syntax with positions in the original file.
+ * Frontmatter is masked so literal YAML values cannot become body markup.
+ * @param {string} source - Complete Markdown source, optionally with frontmatter.
+ * @param {string} file - Diagnostic filename.
+ * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
+ */
+export function markupFindings(source, file) {
+    const body = String(source ?? "").replace(
+        /^\uFEFF?---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/,
+        (frontmatter) => frontmatter.replace(/[^\r\n]/g, " "),
+    );
+    return [...scanBlocks(body).errors, ...scanAlerts(body).errors].map((error) => ({
+        file,
+        ...error,
+        severity: "error",
+    }));
+}

package/engine/note-addresses.mjs

@@ -41,6 +41,7 @@ export {
 
 /** Structured positions whose Address is nested inside a declared container. */
 export const STRUCTURED_ADDRESSES = Object.freeze([
+    { path: ["data", "seeAlso", "*", "address"], shape: "value", lenient: true },
     {
         path: ["packFolder"],
         shape: "scalar-or-map",

package/engine/note-claims.mjs

@@ -666,11 +666,12 @@ function packsServing(config, docType, system) {
  * @param {string} absPath - The note's path, for the finding's position.
  * @param {string} type - The note's type.
  * @param {object} config - The resolved build configuration.
+ * @param {string} [raw] - Source text already read by the caller.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per
  *   discarded block.
  */
-function discardedSystemBlockFindings(fm, absPath, type, config) {
+function discardedSystemBlockFindings(fm, absPath, type, config, raw) {
     const findings = [];
     for (const system of SHIPPED_SYSTEMS) {
         if (!carriesSystemBlock(fm, system)) continue;
@@ -683,7 +684,7 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
         if (!packs || serving) continue;
         findings.push({
             file: absPath,
-            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true }),
+            ...locateFrontmatterKey(absPath, system, undefined, { topLevel: true, raw }),
             severity: /** @type {"error"} */ ("error"),
             type,
             message:
@@ -715,10 +716,16 @@ function discardedSystemBlockFindings(fm, absPath, type, config) {
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
  *   compile and handed in — required, for the reason above.
+ * @param {Map<string, {body: string, raw: string}>} [opts.parsed] - Already parsed
+ *   notes, keyed by file, for body checks and finding positions.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
-export function unclaimedNoteFindings(config = loadPackConfig(), sources, { records } = {}) {
+export function unclaimedNoteFindings(
+    config = loadPackConfig(),
+    sources,
+    { records, parsed } = {},
+) {
     const resolved = resolveSources(sources);
     const vocabulary = noteTypeVocabulary(resolved);
     const findings = [];
@@ -752,17 +759,19 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // Asked first, and asked whatever the type's claim turns out to be: a
         // note whose documents all have packs may still carry a block none of
         // them reads, and that is invisible to every question below.
-        findings.push(...discardedSystemBlockFindings(fm, absPath, type, config));
+        findings.push(
+            ...discardedSystemBlockFindings(fm, absPath, type, config, parsed?.get(absPath)?.raw),
+        );
 
         // Every document this note produces, against the classes this
         // configuration has a pack for. Three outcomes, and the middle one is
         // the half-claimed one — invisible while the question is only "is anything
         // claiming this note", because the answer there is yes.
         const produces = documentClassesFor(type, resolved, {
-            // Lazy: only a doc-carrying type whose JournalEntry has nowhere to
-            // go asks, so a tree with a JournalEntry pack — which is most of
-            // them — reads no bodies at all.
-            hasProse: () => noteHasProse(absPath),
+            hasProse: () => {
+                const source = parsed?.get(absPath);
+                return source ? Boolean(source.body) : noteHasProse(absPath);
+            },
         });
         const missing = produces.filter((docType) => !configured.has(docType));
         const compiled = produces.filter((docType) => configured.has(docType));
@@ -791,7 +800,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         if (compiled.length) {
             findings.push({
                 file: absPath,
-                ...locateFrontmatterKey(absPath, "type", type),
+                ...locateFrontmatterKey(absPath, "type", type, { raw: parsed?.get(absPath)?.raw }),
                 severity: /** @type {"error"} */ ("error"),
                 type,
                 message: partialMessage(type, missing, compiled),
@@ -801,7 +810,7 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
 
         findings.push({
             file: absPath,
-            ...locateFrontmatterKey(absPath, "type", type),
+            ...locateFrontmatterKey(absPath, "type", type, { raw: parsed?.get(absPath)?.raw }),
             severity: /** @type {"error"} */ ("error"),
             type,
             message:

package/engine/note-package.mjs

@@ -62,12 +62,13 @@ export function searchableFrontmatter(fm, configured) {
  * @param {string} [options.absPath] - The note's file on disk, read only on the
  *   failing path to locate the offending line and column. The position rides on
  *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
  * @returns {void}
  * @throws {Error} When the note declares the field.
  */
-export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {}) {
+export function assertNoDeclaredPackage(fm, { file, absPath, configured, raw } = {}) {
     if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "package")) return;
 
     const target = configured ?? contentPackage();
@@ -84,10 +85,7 @@ export function assertNoDeclaredPackage(fm, { file, absPath, configured } = {})
             `\`contentPackage\` ("${target}", in package-build.config.yaml), ` +
             `and every note in the tree belongs to it.`,
     );
-    // Where the field is, so the caller's diagnostic opens on the line that has
-    // to be deleted. Read here rather than carried through every walk: this is
-    // the failing path, and the build stops on it.
-    const position = locateFrontmatterKey(absPath, "package");
+    const position = locateFrontmatterKey(absPath, "package", undefined, { raw });
     if (position) err.position = position;
     throw err;
 }

package/engine/note-vocabulary.mjs

@@ -72,6 +72,7 @@
  * @module
  */
 
+import { checkSeeAlso } from "./see-also.mjs";
 // The one charset, read rather than restated. A second spelling of the pattern
 // is how a disagreement between the three arises.
 import { ART_SLOTS } from "./art-slots.mjs";
@@ -203,7 +204,7 @@ import { checkSettlementTables } from "./settlement-tables.mjs";
  * @property {"pack"} [keys] - For a `scalar-or-map` field, what its keys name.
  *   `"pack"` means each is a pack this package declares, so a key naming none
  *   is a finding of its own: it addresses a hierarchy nothing will ever read.
- * @property {(note: object, opts: {index?: object}) => object[]} [check] - A
+ * @property {(note: object, opts: {index?: object, addressContext?: object}) => object[]} [check] - A
  *   check of the value beyond its shape, run by the frontmatter lint with the
  *   link index once the container has been checked. The lint stays
  *   vocabulary-agnostic this way: the rule lives beside the field that needs
@@ -1001,6 +1002,33 @@ export const NOTE_TOP_LEVEL_KEY_SET = Object.freeze(new Set(NOTE_TOP_LEVEL_KEYS)
  * @type {readonly DataFieldSpec[]}
  */
 export const SHARED_DATA_FIELDS = Object.freeze([
+    Object.freeze({
+        name: "seeAlso",
+        kind: "list",
+        shape: "list of `{ address, gloss? }`",
+        entries: Object.freeze({
+            kind: "map",
+            shape: "`{ address, gloss? }`",
+            fields: Object.freeze([
+                Object.freeze({
+                    name: "address",
+                    kind: "address",
+                    shape: "a note Address",
+                    required: true,
+                    describe: "The note to read next.",
+                }),
+                Object.freeze({
+                    name: "gloss",
+                    kind: "string",
+                    shape: "a string",
+                    describe: "A short phrase saying why to follow the reference.",
+                }),
+            ]),
+        }),
+        check: checkSeeAlso,
+        describe:
+            "Deliberate cross-references in reading order, with optional glosses; shown on the site, in journals and in books.",
+    }),
     Object.freeze({
         name: "id",
         ...TEXT,

package/engine/pdf-build.mjs

@@ -120,6 +120,7 @@ import {
 import { artPathname, assetAddressIndex, pathnameRoles } from "./art-fields.mjs";
 import { embedRole } from "./content-embeds.mjs";
 import { expandContentTables } from "./content-tables.mjs";
+import { seeAlsoEntries, seeAlsoMarkdown, seeAlsoWebLink } from "./see-also.mjs";
 import { renderMarkdownExpressions } from "./markdown-expressions.mjs";
 import { eventNoteIndex } from "./event-fields.mjs";
 import { numberFigures, scanFigures } from "./content-figures.mjs";
@@ -1645,7 +1646,13 @@ async function buildBook(book, shared) {
         // Whether the entry is settled comes before anything it says: the
         // notice leads the leaf, before the authored body.
         const notice = isDraftNote(page.fm) ? draftNoticeTypst() : "";
-        const parts = [notice, prose, panel].filter((part) => part);
+        const references = seeAlsoMarkdown(
+            seeAlsoEntries(page.fm, (ref) => resolveInfoboxRef(gates.index, ref)),
+            seeAlsoWebLink,
+        );
+        const parts = [notice, prose, panel, references ? typst(references, {}) : ""].filter(
+            (part) => part,
+        );
         return parts.join("\n\n");
     };
 

package/engine/prose-lint.mjs

@@ -43,6 +43,7 @@ import {
     sharedPrettierDivergence,
     sharedPrettierOptionsFor,
 } from "./prose-config.mjs";
+import { markupFindings } from "./markup-validation.mjs";
 import { MarkdownConfigError, runMarkdownlint } from "./markdownlint-run.mjs";
 import { walkFiles } from "./walk-files.mjs";
 
@@ -152,6 +153,13 @@ export async function checkFormatting(root, opts = {}) {
             filepath: file,
         };
         const source = fs.readFileSync(file, "utf8");
+        if (["markdown", "mdx"].includes(info.inferredParser)) {
+            const syntaxErrors = markupFindings(source, file);
+            if (syntaxErrors.length) {
+                findings.push(...syntaxErrors);
+                continue;
+            }
+        }
 
         // A file Prettier cannot parse is a finding, not a crash. Its own CLI
         // reports the syntax error and carries on to the next file, and a
@@ -399,9 +407,9 @@ export async function lintMarkdown(root, opts = {}) {
     const { paths, fix = false } = opts;
     const directory = path.resolve(root);
 
-    let results;
+    let results, markup;
     try {
-        ({ results } = await runMarkdownlint({
+        ({ results, markup } = await runMarkdownlint({
             directory,
             globs: paths,
             fix,
@@ -430,8 +438,6 @@ export async function lintMarkdown(root, opts = {}) {
         };
     }
 
-    return {
-        findings: results.map((result) => toDiagnostic(directory, result)),
-        exitCode: results.length ? 1 : 0,
-    };
+    const findings = [...results.map((result) => toDiagnostic(directory, result)), ...markup];
+    return { findings, exitCode: findings.length ? 1 : 0 };
 }

package/engine/related-pages.mjs

@@ -27,11 +27,12 @@
  * `<type>-<shortcode>` form: the site index keys one page under both, and both
  * answer with one URL.
  *
- * **Only a page of this site is an endpoint.** A link into another package
+ * **Only a page of this site is an inferred endpoint.** A link into another package
  * resolves to a URL the build renders but no page it writes, so it appears
  * on neither side: a backlink can only be counted on a page this build emits,
  * and listing a foreign mention beside local ones would make the two lists
- * disagree about what a connection is.
+ * disagree about what a connection is. Deliberate see-also references also
+ * name pages in declared dependencies.
  *
  * @module
  */
@@ -46,6 +47,7 @@ import { homepageAddresses } from "./homepage.mjs";
  * @property {string} url   `<base><slug>/` — the page's address as every href
  *                          this build renders composes it, never the
  *                          site-root-relative form the page states for itself.
+ * @property {string} [gloss] Why the author recommends this page.
  * @property {string} type  The note's `type`, which the theme groups by.
  */
 
@@ -53,6 +55,7 @@ import { homepageAddresses } from "./homepage.mjs";
  * The `related` block one page publishes.
  *
  * @typedef {object} Related
+ * @property {RelatedEntry[]} [seeAlso] Deliberate references in authored order.
  * @property {RelatedEntry[]} backlinks Pages that link to this one.
  * @property {RelatedEntry[]} mentions  Pages this one links to.
  */
@@ -89,10 +92,11 @@ function byTypeThenTitle(a, b) {
  *   the source page's URL and the target page's.
  * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
  *   site, keyed by URL.
+ * @param {ReadonlyMap<string, RelatedEntry[]>} [deliberate] Authored references, including foreign destinations.
  * @returns {Map<string, Related>} URL → the page's `related` block, both lists
  *   sorted, for every page with at least one entry in either.
  */
-export function relatedPages(edges, entries) {
+export function relatedPages(edges, entries, deliberate = new Map()) {
     /** @type {Map<string, {backlinks: Set<string>, mentions: Set<string>}>} */
     const graph = new Map();
     const node = (url) => {
@@ -120,6 +124,21 @@ export function relatedPages(edges, entries) {
     for (const [url, { backlinks, mentions }] of graph) {
         out.set(url, { backlinks: list(backlinks), mentions: list(mentions) });
     }
+    for (const [url, refs] of deliberate) {
+        const seen = new Set([url]);
+        const seeAlso = refs.filter((ref) => {
+            if (seen.has(ref.url)) return false;
+            seen.add(ref.url);
+            return true;
+        });
+        if (!seeAlso.length) continue;
+        const block = out.get(url) ?? { backlinks: [], mentions: [] };
+        out.set(url, {
+            seeAlso,
+            backlinks: block.backlinks.filter((ref) => !seen.has(ref.url)),
+            mentions: block.mentions.filter((ref) => !seen.has(ref.url)),
+        });
+    }
     return out;
 }
 

package/engine/see-also.mjs

@@ -0,0 +1,150 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+import { parseAddress, renderAddress, hasAnchor } from "./address.mjs";
+import { ASSET_TYPE_NAMES } from "./asset-types.mjs";
+import { positionOfFrontmatterPath } from "./diagnostics.mjs";
+
+/**
+ * Validate note references, refusing unresolved, repeated and self destinations.
+ * @param {object} note - The authored note, including its raw source.
+ * @param {object} [options] - The local and declared dependency context.
+ * @param {object} [options.index] - The local and declared dependency index.
+ * @param {string} [options.index.contentPackage] - The package owning the note.
+ * @param {Set<string>} [options.index.types] - The indexed note types.
+ * @param {Set<string>} [options.index.packages] - The indexed packages.
+ * @param {(key: string) => {url?: string, uuid?: string, file?: string}|undefined}
+ *   [options.index.addressHit] - Resolve a canonical Address to its destination.
+ * @param {import("./address.mjs").AddressDefaults} [options.addressContext]
+ *   - The Address defaults and vocabularies at the authored reference.
+ * @returns {object[]} Findings located at the offending address.
+ */
+export function checkSeeAlso(note, { index, addressContext } = {}) {
+    const entries = note.fm?.data?.seeAlso;
+    if (!Array.isArray(entries)) return [];
+    const defaults = {
+        package: index?.contentPackage,
+        system: "note",
+        types: index?.types,
+        packages: index?.packages,
+        ...addressContext,
+        type: undefined,
+    };
+    const own = parseAddress(note.fm.shortcode, { ...defaults, type: note.fm.type });
+    const seen = new Set();
+    const findings = [];
+    entries.forEach((entry, i) => {
+        if (entry === null) {
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(note.raw ?? "", ["data", "seeAlso", i]),
+                severity: "error",
+                message: `\`data.seeAlso.${i}\` should be a map with an address`,
+            });
+            return;
+        }
+        if (!entry || typeof entry !== "object" || entry.address == null) return;
+        const tuple = parseAddress(entry.address, defaults, { declared: true });
+        const key = tuple.reason ? undefined : renderAddress(tuple);
+        const target = key ? index?.addressHit?.(key) : undefined;
+        const destination = target?.url ?? target?.uuid ?? target?.file ?? key;
+        const self =
+            (!own.reason &&
+                tuple.package === own.package &&
+                tuple.type === own.type &&
+                tuple.shortcode === own.shortcode) ||
+            (target?.file && target.file === note.file);
+        const reason =
+            hasAnchor(entry.address) ? "takes no anchor — it names a whole note"
+            : tuple.reason || ASSET_TYPE_NAMES.has(tuple.type) ? "should be a note Address"
+            : index?.addressHit && !target ?
+                "does not resolve in this package or its declared dependencies"
+            : self ? "names the note itself"
+            : seen.has(destination) ? "is a duplicate destination"
+            : undefined;
+        seen.add(destination);
+        if (reason)
+            findings.push({
+                file: note.file,
+                ...positionOfFrontmatterPath(note.raw ?? "", ["data", "seeAlso", i, "address"]),
+                severity: "error",
+                message: `\`data.seeAlso.${i}.address\` ${reason}`,
+            });
+    });
+    return findings;
+}
+
+/**
+ * Resolve deliberate references in authored order using the surface's index.
+ * @param {object} fm - The note frontmatter.
+ * @param {(address: unknown) => object|undefined} resolve - The surface's reference resolver.
+ * @returns {object[]} Display names, destinations and optional glosses.
+ */
+export function seeAlsoEntries(fm, resolve) {
+    const entries = fm?.data?.seeAlso;
+    if (!Array.isArray(entries)) return [];
+    return entries.flatMap((entry) => {
+        const target = entry?.address == null ? undefined : resolve(entry.address);
+        if (!target) return [];
+        return [{ ...target, text: target.name, ...(entry.gloss ? { gloss: entry.gloss } : {}) }];
+    });
+}
+
+/** Plain text in a generated Markdown paragraph. */
+const plain = (text) =>
+    String(text ?? "")
+        .replace(/([\\`*_[\]<>{}|#!~])/g, "\\$1")
+        .replace(/\r?\n/g, " ");
+
+/**
+ * A generated section; an empty list emits nothing.
+ * @param {object[]} entries - Resolved references in authored order.
+ * @param {(entry: object) => string} link - The medium's link markup.
+ * @param {number} [level=2] - Heading level; a journal uses one for a separate page.
+ * @returns {string} Markdown for the section.
+ */
+export function seeAlsoMarkdown(entries, link, level = 2) {
+    if (!entries.length) return "";
+    return `${"#".repeat(level)} See also\n\n${entries.map((entry) => `- ${link(entry)}${entry.gloss ? ` — ${plain(entry.gloss)}` : ""}`).join("\n")}\n`;
+}
+
+/**
+ * A reference rendered as an ordinary Markdown link for the book pipeline.
+ * @param {object} entry - A resolved name and URL.
+ * @returns {string} Markdown.
+ */
+export function seeAlsoWebLink(entry) {
+    return entry.url ? `[${plain(entry.text)}](<${entry.url}>)` : plain(entry.text);
+}
+
+/**
+ * Deliberate site connections for a set of pages, including dependency pages.
+ * @param {object[]} pages - Pages carrying frontmatter and their published URL.
+ * @param {(address: unknown) => object|undefined} resolve - The site's reference resolver.
+ * @returns {Map<string, import("./related-pages.mjs").RelatedEntry[]>} Entries keyed by source URL.
+ */
+export function seeAlsoPages(pages, resolve) {
+    const deliberate = new Map();
+    for (const page of pages) {
+        const refs = seeAlsoEntries(page.fm, resolve)
+            .filter((ref) => ref.url)
+            .map((ref) => ({
+                title: ref.name,
+                url: ref.url,
+                type: ref.address.type,
+                ...(ref.gloss ? { gloss: ref.gloss } : {}),
+            }));
+        if (refs.length) deliberate.set(page.url, refs);
+    }
+    return deliberate;
+}

package/engine/site-build.mjs

@@ -109,6 +109,7 @@ import {
 } from "./homepage.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
+import { seeAlsoPages } from "./see-also.mjs";
 import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
 import { drawSiteMaps, inlineDrawingFigure } from "./site-maps.mjs";
 import { generatedDrawing, markGenerated, splitGenerated } from "./generated-sections.mjs";
@@ -1095,7 +1096,10 @@ export function renderPages(pages, options) {
         for (const hit of result.resolved) if (hit.url) edges.push([page.url, hit.url]);
     }
 
-    const related = relatedPages(edges, entries);
+    const deliberate = seeAlsoPages([...pages, ...homepages], (ref) =>
+        resolveInfoboxRef(index, ref),
+    );
+    const related = relatedPages(edges, entries, deliberate);
 
     let withMap = 0;
     const outputs = capture === true ? new Map() : null;