@heroiclands/package-build 22.4.3 → 22.4.4

package/CHANGELOG.md

@@ -1,45 +1,37 @@
 # @heroiclands/package-build
 
+## 22.4.4
+
+### Patch Changes
+
+Every page a site build publishes carries a `related` block in its front matter — the pages that link to it and the pages it links to, each named once with its title, address and type — which the theme renders as the Related card at the foot of the page. A page nothing connects to carries no block, and the homepage is counted on both sides like any other page.
+
+`changelog group` keeps a hard-wrapped paragraph as one block instead of fragmenting it one block per line, and no longer inserts a blank line under a bold sentence a paragraph continues directly beneath.
+
 ## 22.4.3
 
 ### Patch Changes
 
+**A new `changelog group` command folds a release's changeset blocks together by their bold label.**
 `@heroiclands/package-build/changelog` writes each changeset's summary into `CHANGELOG.md` as its
-
 own block, so three pull requests each touching compendium content leave three separate
-
 `**Compendiums**` blocks instead of one. `changelog group` rewrites the newest release section in
-
 place: every block sharing one label is merged into a single block, bullets kept in their original
-
 order with an exact duplicate kept once, and the merged blocks are ordered by a new
-
 `changelog.labels` configuration key — the unlabelled lead paragraph first, then every declared
-
 label in order, then any undeclared label last with a warning naming it. `changelog check` warns on
-
 a label absent from a declared `changelog.labels` too, so a drifted spelling is caught before a
-
 release ships it.
 
+**A shipped changelog generator writes a release note without a commit hash.**
 `@heroiclands/package-build/changelog` is a Changesets changelog generator
-
 whose `getReleaseLine` renders a changeset's summary as a block, verbatim —
-
 no bullet, no indentation, separated from its neighbours by one blank line —
-
 and whose `getDependencyReleaseLine` writes nothing. Point
-
 `.changeset/config.json` at it
-
 (`"changelog": "@heroiclands/package-build/changelog"`) to stop every release
-
 note from carrying a commit-hash prefix.
 
-**A new `changelog group` command folds a release's changeset blocks together by their bold label.**
-
-**A shipped changelog generator writes a release note without a commit hash.**
-
 ## 22.4.2
 
 ### Patch Changes

package/CONTENT.md

@@ -2333,6 +2333,53 @@ notes it lists, and link it from the homepage. Nothing is generated between
 the homepage and the pages, so delete the key.
 ````
 
+### Every page carries what links to it, and what it links to
+
+The build resolves every wikilink on every page through the address index, so
+at the moment it writes a page it holds the whole link graph. It writes the
+part that concerns each page into that page's front matter:
+
+```yaml
+related:
+  backlinks: # pages that link to this one
+    - title: Afzandah Parnâzar
+      url: /thalorna/being-afzndhprnzr/
+      type: being
+  mentions: # pages this one links to
+    - title: Kethramír
+      url: /thalorna/place-kthrmr/
+      type: place
+```
+
+The theme's `related.html` partial reads both lists and renders them as one
+"Related" card, grouped by `type`. What the build guarantees about them:
+
+- **A page appears once per list**, however many times it is linked, and
+  whichever address the link was written to: `docbeing-grod` and `being-grod`
+  are one page, and a page that cites it under both lists it once. A link from
+  a page to itself is not a connection and is dropped.
+- **Each list is sorted by `type`, then `title`**, so the card's grouping is
+  the same on every build whatever order the notes were walked in.
+- **Both lists are present whenever either has an entry**, so a theme reads one
+  shape; a page with no links either way carries **no `related` key at all**,
+  which is the partial's silent-disappear convention kept at the source.
+- **`url` composes `<base><slug>/`**, like every other href this build renders
+  — see [A page's URL is its address](#a-pages-url-is-its-address). The page
+  states its own address as `/<slug>/`; everything pointing _at_ it, this
+  included, carries the base.
+- **The homepage is a page like any other on both sides.** A content page
+  reaches it through `[[homepage-root|Text]]` and is listed in its backlinks;
+  its own body links are ordinary markdown, resolved against the package root
+  the way a browser resolves them, so `being-grod/`, `/thalorna/being-grod/`
+  and `./being-grod/#top` each count as a mention of that page. A link that
+  names a host leaves the site and counts as nothing.
+- **Only a page of this site is an endpoint.** A link into another package
+  resolves to an href the build renders but no page it writes, so it is listed
+  on neither side; a backlink can be counted only on a page this build emits.
+
+`related` is derived, never authored: what links to a page is a fact about
+every other page in the tree. A note that writes one has it replaced.
+
 ### Why the output location is fixed
 
 The content mount is a build artifact and is **deleted on every run**, so that a

package/engine/changelog-group.mjs

@@ -50,13 +50,22 @@ const CHANGES_HEADING_RE = /^### (?:Major|Minor|Patch) Changes$/gm;
  *
  * @param {string} blockText - One block, as {@link topLevelBlocks} collects
  *   it — its first line is the label line for a labelled block.
- * @returns {{labelLine: string, rest: string}} `rest` has its leading blank
- *   line dropped; a block with nothing but the label line yields `""`.
+ * @returns {{labelLine: string, rest: string, hadBlankLine: boolean}} `rest`
+ *   has its leading blank line dropped; a block with nothing but the label
+ *   line yields `""`. `hadBlankLine` says whether the label line was
+ *   followed by a blank line in `blockText` — false for a bold sentence a
+ *   hard-wrapped paragraph continues directly beneath, with no blank line
+ *   of its own.
  */
 function splitLabelLine(blockText) {
     const nl = blockText.indexOf("\n");
-    if (nl === -1) return { labelLine: blockText, rest: "" };
-    return { labelLine: blockText.slice(0, nl), rest: blockText.slice(nl + 1).replace(/^\n+/, "") };
+    if (nl === -1) return { labelLine: blockText, rest: "", hadBlankLine: false };
+    const after = blockText.slice(nl + 1);
+    return {
+        labelLine: blockText.slice(0, nl),
+        rest: after.replace(/^\n+/, ""),
+        hadBlankLine: after.startsWith("\n"),
+    };
 }
 
 /**
@@ -115,6 +124,14 @@ function joinItems(items) {
  * One label's blocks (or every unlabelled one), folded into the single
  * block `group` writes for it.
  *
+ * A single, unmerged block — the common case, one changeset writing one
+ * label once — keeps its own label-to-body separator rather than forcing a
+ * blank line: a bold sentence a hard-wrapped paragraph continues directly
+ * beneath must round-trip unchanged, not gain a blank line it never had.
+ * Merging two or more blocks, or a label whose lone block carries several
+ * items (bullets), still separates the label from its body with a blank
+ * line — the convention every existing multi-item block already uses.
+ *
  * @param {Array<{label: string|null, text: string}>} blocks - Every block
  *   sharing one label, in file order. All carry the same `label`.
  * @returns {string}
@@ -123,9 +140,13 @@ function mergeGroup(blocks) {
     if (blocks[0].label === null) {
         return joinItems(dedupeItems(blocks.flatMap((block) => itemsOf(block.text))));
     }
-    const { labelLine } = splitLabelLine(blocks[0].text);
+    const { labelLine, hadBlankLine } = splitLabelLine(blocks[0].text);
     const items = dedupeItems(blocks.flatMap((block) => itemsOf(splitLabelLine(block.text).rest)));
-    return items.length ? `${labelLine}\n\n${joinItems(items)}` : labelLine;
+    if (items.length === 0) return labelLine;
+    if (blocks.length === 1 && items.length === 1) {
+        return `${labelLine}${hadBlankLine ? "\n\n" : "\n"}${items[0]}`;
+    }
+    return `${labelLine}\n\n${joinItems(items)}`;
 }
 
 /**

package/engine/changelog-lint.mjs

@@ -234,13 +234,15 @@ export function topLevelBullets(text, codeLines) {
  * {@link topLevelBullets}, where a bullet marker *is* the top-level
  * construct — a `-` bullet at column 0 belongs to whatever block is
  * already open, since a label's bullets sit unindented directly under it.
- * Any other column-0 line (plain prose with no label, a bullet with no
- * block open yet) starts the one "lead" block (`label: null`) a changeset
- * with no category writes — the case `changelog group` sorts first and
- * `check` never flags. Nested detail — a wrapped line, a bullet's own
- * continuation — stays indented and belongs to whatever it follows.
- * `changelog group` folds same-label blocks together; `check` warns when a
- * block's label is not in the declared vocabulary.
+ * A plain column-0 line that is neither a label nor a bullet continues
+ * whatever block is open, because Prettier's `proseWrap` puts every line of
+ * a hard-wrapped paragraph at column 0 — it starts a new "lead" block
+ * (`label: null`) only at a paragraph boundary, the start of the section or
+ * a line right after a blank one, which is the case `changelog group`
+ * sorts first and `check` never flags. A blank line never closes a block by
+ * itself; it only ends the run of continuation lines a following column-0
+ * line can attach to. `changelog group` folds same-label blocks together;
+ * `check` warns when a block's label is not in the declared vocabulary.
  *
  * @param {string} text - Section text.
  * @param {Set<number>} codeLines - Lines inside a code region, from
@@ -266,6 +268,9 @@ export function topLevelBlocks(text, codeLines, scaffoldLines = new Set()) {
             });
         current = null;
     };
+    // A paragraph boundary — the start of the section, or right after a
+    // blank line — is the only place an unlabelled lead block may start.
+    let afterBlank = true;
 
     for (let i = 0; i < lines.length; i++) {
         const lineNo = i + 1;
@@ -273,29 +278,44 @@ export function topLevelBlocks(text, codeLines, scaffoldLines = new Set()) {
 
         if (codeLines.has(lineNo)) {
             if (current) current.parts.push(raw);
+            afterBlank = raw.trim() === "";
             continue;
         }
         if (scaffoldLines.has(lineNo)) {
             close();
+            afterBlank = true;
             continue;
         }
         const atColumnZero = raw.trim() !== "" && !/^[ \t]/.test(raw);
         if (!atColumnZero) {
             if (current) current.parts.push(raw);
+            afterBlank = raw.trim() === "";
             continue;
         }
         const label = LABEL_LINE_RE.exec(raw)?.[1] ?? null;
         if (label !== null) {
             close();
             current = { startLine: lineNo, label, parts: [raw] };
+            afterBlank = false;
             continue;
         }
         if (TOP_BULLET_RE.test(raw) && current) {
             current.parts.push(raw);
+            afterBlank = false;
+            continue;
+        }
+        // Plain prose at column 0: it continues whatever block is already
+        // open unless it opens a new paragraph — Prettier's `proseWrap`
+        // puts every line of a hard-wrapped paragraph at column 0, so a
+        // continuation line must never be read as a new lead block.
+        if (current && !afterBlank) {
+            current.parts.push(raw);
+            afterBlank = false;
             continue;
         }
         close();
         current = { startLine: lineNo, label: null, parts: [raw] };
+        afterBlank = false;
     }
     close();
     return blocks;

package/engine/homepage.mjs

@@ -378,15 +378,23 @@ export function homepageTitle(fm, config) {
  * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
+ * `related` is derived like every other page's — what links to the homepage
+ * is a fact about the rest of the tree — so an authored value is dropped and
+ * the caller's block, where it has one, is written in its place.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
+ * @param {object} [options.related] - The homepage's backlinks and mentions,
+ *   where the site build found either.
  * @returns {object} The frontmatter to write.
  */
-export function homepageFrontmatter(fm, { contentPackage, title }) {
+export function homepageFrontmatter(fm, { contentPackage, title, related }) {
     const data = { ...fm, package: contentPackage, title };
     delete data.aliases;
+    delete data.related;
+    if (related) data.related = related;
     return data;
 }
 

package/engine/related-pages.mjs

@@ -0,0 +1,161 @@
+/*
+ * 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
+ */
+
+/**
+ * What links to a page, and what it links to.
+ *
+ * The site build resolves every wikilink through the address index, so by the
+ * time it writes a page it holds the whole link graph. This is the half that
+ * turns the graph into front matter: the `related` block the theme's Related
+ * card reads, on every page, in one shape.
+ *
+ * **A page is identified by its URL.** An address is unique within a package
+ * and a page publishes at exactly one, so the URL is the one key both a
+ * resolved wikilink and a homepage's markdown link can be reduced to — the
+ * link resolver answers with a URL, and a homepage link *is* one. It is also
+ * what makes a `doc<type>-<shortcode>` link a link to the same page as the
+ * `<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
+ * 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.
+ *
+ * @module
+ */
+
+import { homepageAddresses } from "./homepage.mjs";
+
+/**
+ * One entry in a `related` list — the page a reader is pointed at.
+ *
+ * @typedef {object} RelatedEntry
+ * @property {string} title The page's published title.
+ * @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} type  The note's `type`, which the theme groups by.
+ */
+
+/**
+ * The `related` block one page publishes.
+ *
+ * @typedef {object} Related
+ * @property {RelatedEntry[]} backlinks Pages that link to this one.
+ * @property {RelatedEntry[]} mentions  Pages this one links to.
+ */
+
+/**
+ * A stable order for a list: by type, then title.
+ *
+ * The theme groups a list by type and reads each group in the order it
+ * arrives, so the order is fixed here rather than left to walk order — which
+ * is content-path order, and would reshuffle a page's card whenever a note was
+ * filed elsewhere.
+ *
+ * @param {RelatedEntry} a
+ * @param {RelatedEntry} b
+ * @returns {number}
+ */
+function byTypeThenTitle(a, b) {
+    return a.type.localeCompare(b.type, "en") || a.title.localeCompare(b.title, "en");
+}
+
+/**
+ * Inverts a link graph into each page's backlinks and mentions.
+ *
+ * An edge is `(source URL, target URL)`, and a URL that is not in `entries` is
+ * not a page of this site, so an edge touching one is dropped. A self-link says
+ * nothing a reader is not already looking at, and a page that links another
+ * three times is connected to it once, so both collapse.
+ *
+ * The result holds only pages with at least one connection, so the caller can
+ * write nothing on a page with none — the theme's silent-disappear convention,
+ * kept at the source rather than papered over with an empty block.
+ *
+ * @param {Iterable<readonly [string, string]>} edges - Every resolved link, as
+ *   the source page's URL and the target page's.
+ * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
+ *   site, keyed by URL.
+ * @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) {
+    /** @type {Map<string, {backlinks: Set<string>, mentions: Set<string>}>} */
+    const graph = new Map();
+    const node = (url) => {
+        let found = graph.get(url);
+        if (!found) {
+            found = { backlinks: new Set(), mentions: new Set() };
+            graph.set(url, found);
+        }
+        return found;
+    };
+
+    for (const [source, target] of edges) {
+        if (source === target) continue;
+        if (!entries.has(source) || !entries.has(target)) continue;
+        node(source).mentions.add(target);
+        node(target).backlinks.add(source);
+    }
+
+    const list = (urls) =>
+        [...urls]
+            .map((url) => /** @type {RelatedEntry} */ (entries.get(url)))
+            .sort(byTypeThenTitle);
+
+    const out = new Map();
+    for (const [url, { backlinks, mentions }] of graph) {
+        out.set(url, { backlinks: list(backlinks), mentions: list(mentions) });
+    }
+    return out;
+}
+
+/**
+ * The pages a homepage's body links to, as URLs.
+ *
+ * A homepage is published verbatim — no wikilink on it resolves, and its links
+ * are ordinary markdown the browser resolves against the page's own address,
+ * which is the package root. So its edges are read the same way: each target
+ * resolved against `base`, the way a browser would. A package-relative
+ * `being-x/`, a root-relative `/pkg/being-x/` and a `./being-x/#anchor` all
+ * name the same page; a bare `#anchor` names the homepage itself.
+ *
+ * A link that names a host or a scheme leaves the site, whatever path it
+ * carries, and yields nothing: the site's own pages are addressed without one.
+ *
+ * @param {string} body - The homepage's markdown body.
+ * @param {string} base - Where the package is served — the homepage's own URL.
+ * @returns {string[]} The targets' URLs, in body order, repeats included.
+ */
+export function homepageLinkTargets(body, base) {
+    const out = [];
+    // A placeholder origin, so a relative target resolves the way a browser
+    // resolves it from the homepage. It never reaches the result: only the
+    // path is read, and only when the target stayed on this origin.
+    const origin = "http://site.invalid";
+    for (const { url } of homepageAddresses(body)) {
+        if (/^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith("//")) continue;
+        let resolved;
+        try {
+            resolved = new URL(url, `${origin}${base}`);
+        } catch {
+            continue;
+        }
+        if (resolved.origin !== origin) continue;
+        out.push(resolved.pathname);
+    }
+    return out;
+}

package/engine/site-build.mjs

@@ -81,6 +81,7 @@ import {
 } from "./homepage.mjs";
 import { publishesContentPages } from "../content-config.mjs";
 import { HUGO_CONTENT } from "./site-config.mjs";
+import { homepageLinkTargets, relatedPages } from "./related-pages.mjs";
 
 const require = createRequire(import.meta.url);
 
@@ -291,18 +292,30 @@ export function collectHomepages(contentBase, ctx) {
  * states no `url` — the home kind has none to state — and the mount below it
  * holds pages and nothing else, so this is the only `_index.md` in the tree.
  *
+ * **Verbatim, but not unconnected.** The homepage is a page like any other on
+ * both sides of the link graph: a content page reaches it through
+ * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
+ * it carries the same `related` block every content page does — handed in by
+ * the caller, since the graph is read off the content render and homepage-only
+ * mode has none.
+ *
  * @param {string} outRoot - The package's site root — the content mount's
  *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
+ * @param {object} [options] - Options.
+ * @param {import("./related-pages.mjs").Related} [options.related] - The
+ *   homepage's backlinks and mentions. Absent where nothing connects to it,
+ *   and in homepage-only mode, where no link resolves.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot, pages, config) {
+export function writeHomepages(outRoot, pages, config, { related } = {}) {
     for (const page of pages) {
         const data = homepageFrontmatter(page.fm, {
             contentPackage: config.contentPackage,
             title: homepageTitle(page.fm, config),
+            related,
         });
         const dest = path.join(outRoot, HOMEPAGE_DESTINATION);
         fs.mkdirSync(path.dirname(dest), { recursive: true });
@@ -472,6 +485,12 @@ export function tableUniverse(pages) {
  * self-describing and makes sweeping the field out of a content tree
  * output-preserving for a site as it already is for the packs.
  *
+ * **`related` is derived, never authored.** What links to a page is a fact
+ * about every other page, known only once the whole tree has resolved — see
+ * {@link module:engine/related-pages} — so an authored value is dropped the
+ * way `aliases` is, and {@link renderPages} writes the derived block once it
+ * holds the graph.
+ *
  * @param {object} page - The page.
  * @param {object} options
  * @param {(data: object, page: object) => void} [options.decorate] - Called
@@ -486,7 +505,7 @@ export function tableUniverse(pages) {
  * @returns {object} The frontmatter to write.
  */
 export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
-    const { fm, name, slug } = page;
+    const { fm, slug } = page;
     const data = {
         ...fm,
         // Spread after the note's own frontmatter. Guarded because
@@ -500,15 +519,31 @@ export function pageFrontmatter(page, { decorate, webSrc, artSrc }) {
         // from the filename.
         slug,
         url: `/${slug}/`,
-        title: fm.title ?? name,
+        title: pageTitle(page),
         kbfolder: page.folder,
     };
     if (decorate) decorate(data, page);
     delete data.aliases;
+    delete data.related;
     if (webSrc && artSrc) resolveArtFields(data, webSrc, artSrc);
     return data;
 }
 
+/**
+ * The title a content page publishes under: an authored `title`, else the
+ * note's name.
+ *
+ * One rule, read by the page's own front matter and by every `related` entry
+ * that names the page, so a card lists a page by exactly the title its heading
+ * shows.
+ *
+ * @param {object} page - The page, from {@link collectContentPages}.
+ * @returns {string} The title.
+ */
+function pageTitle(page) {
+    return page.fm.title ?? page.name;
+}
+
 /**
  * Rewrite a page's artwork addresses into the URLs the website serves.
  *
@@ -585,10 +620,23 @@ export function pageDestination(page) {
  *    touches, so the repository's own rewrite runs before the shared one
  *    rather than replacing it.
  *
+ * **Every page is rendered before any is written.** What links *to* a page is
+ * known only once every other page has resolved, and it is written into the
+ * page's own front matter, so the render is one pass over the tree and the
+ * write is a second — with the link graph read off the first, at the one
+ * point the resolver answers, and inverted once between them. Nothing is
+ * resolved twice.
+ *
  * @param {object[]} pages - Every page.
- * @param {object} options - Everything the render needs.
+ * @param {object} options - Everything the render needs. `homepages` is the
+ *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
+ *   no part in the render and every part in the graph: a content page links
+ *   it by wikilink, and its own markdown links name content pages.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[]}}
+ *   wikiErrors: object[], imageErrors: object[],
+ *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   is keyed by page URL, and holds the homepage's block beside every content
+ *   page's, so the caller can write it on the page this render does not.
  */
 export function renderPages(pages, options) {
     const {
@@ -602,6 +650,7 @@ export function renderPages(pages, options) {
         sqlTables,
         config,
         records = [],
+        homepages = [],
     } = options;
 
     // The address space the art slots and the body's embeds resolve against:
@@ -616,6 +665,29 @@ export function renderPages(pages, options) {
     const wikiErrors = [];
     const imageErrors = [];
     const byKind = {};
+    // The link graph, as `(source URL, target URL)` — read off each page's
+    // resolution below, and off the homepage's markdown links.
+    /** @type {Array<[string, string]>} */
+    const edges = [];
+    // Every page of this site, as a `related` entry names it.
+    /** @type {Map<string, import("./related-pages.mjs").RelatedEntry>} */
+    const entries = new Map();
+    for (const page of pages) {
+        entries.set(page.url, {
+            title: pageTitle(page),
+            url: page.url,
+            type: String(page.fm.type),
+        });
+    }
+    for (const home of homepages) {
+        entries.set(home.url, { title: home.title, url: home.url, type: String(home.fm.type) });
+        for (const target of homepageLinkTargets(home.body, home.url)) {
+            edges.push([home.url, target]);
+        }
+    }
+    // What each page renders as, held until the graph is whole.
+    /** @type {Array<{page: object, body: string, data: object}>} */
+    const rendered = [];
 
     /**
      * The address the website serves for one authored pathname.
@@ -661,6 +733,8 @@ export function renderPages(pages, options) {
         // The page's path in the tree an author edits, below the content
         // root.
         const src = page.relPath ?? page.base;
+        // Every index entry a link on this page resolved to.
+        const resolved = [];
         const ctx = wikiContext(index, {
             src,
             file: page.file,
@@ -668,6 +742,7 @@ export function renderPages(pages, options) {
             errors: wikiErrors,
             foreignIndex: foreign.index,
             assets: artIndex,
+            resolved,
         });
 
         const webSrc = webAddresses(page.file);
@@ -699,13 +774,26 @@ export function renderPages(pages, options) {
         tableErrors.push(...errors);
 
         const data = pageFrontmatter(page, { decorate, webSrc, artSrc });
+        rendered.push({ page, body: protectCode(body, resolve), data });
+        // A resolved target with no URL is a pack-only package's address:
+        // real, and nowhere on the web, so not an edge.
+        for (const hit of resolved) {
+            if (hit.url) edges.push([page.url, hit.url]);
+        }
+    }
+
+    const related = relatedPages(edges, entries);
+
+    for (const { page, body, data } of rendered) {
+        const block = related.get(page.url);
+        if (block) data.related = block;
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
+        fs.writeFileSync(dest, matter.stringify(body, data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
-    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors };
+    return { written: pages.length, byKind, tableErrors, wikiErrors, imageErrors, related };
 }
 
 /**
@@ -892,11 +980,17 @@ export function buildSite({ config, sqlTables } = {}) {
     // homepage is authored markdown published verbatim, with no table
     // expansion and no link resolution of its own, and routing it through
     // that pipeline would buy it a pass it has no input for.
+    //
+    // It is a node of the link graph all the same: `renderPages` reads its
+    // markdown links for the edges it authors, and the resolver records the
+    // ones that land on it.
     const homepageEntries = homepages.map((page) => ({
         kind: "content",
         fm: page.fm,
+        body: page.body,
         pkg: resolved.contentPackage,
         name: page.fm.name?.full ?? homepageTitle(page.fm, resolved),
+        title: homepageTitle(page.fm, resolved),
         slug: addressSlug(page.fm),
         base: path.basename(page.file),
         url: base,
@@ -926,6 +1020,7 @@ export function buildSite({ config, sqlTables } = {}) {
         index: gates.index,
         foreign: gates.foreign,
         universe: tableUniverse(pages),
+        homepages: homepageEntries,
         pass,
         // What counts as a being is the toolchain's to say, not a consumer's.
         // Asking in a consumer's script is how one came to still be checking
@@ -947,8 +1042,11 @@ export function buildSite({ config, sqlTables } = {}) {
     });
 
     // Last, and outside the mount: the package's front page is not part of the
-    // content tree it introduces.
-    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved);
+    // content tree it introduces. It publishes at `base`, which is where the
+    // graph keys its block.
+    const homepagesWritten = writeHomepages(homeRoot, homepages, resolved, {
+        related: rendered.related.get(base),
+    });
 
     return {
         gates,

package/engine/site-index.mjs

@@ -289,6 +289,9 @@ export function buildSiteIndex(
  *   resolvers that distinguish a foreign hit from a local one.
  * @param {object} [options.assets] - The address space an `![[…]]` embed
  *   resolves against, shaped as every asset resolver reads one.
+ * @param {object[]} [options.resolved] - Collector the resolver appends every
+ *   resolved target's index entry to — the page's outbound edges, read off
+ *   the one pass that resolves them.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -299,7 +302,7 @@ export function buildSiteIndex(
  */
 export function wikiContext(
     built,
-    { src, file, type = null, errors, foreignIndex = new Map(), assets },
+    { src, file, type = null, errors, foreignIndex = new Map(), assets, resolved },
 ) {
     return {
         index: built.index,
@@ -321,6 +324,7 @@ export function wikiContext(
         errors,
         src,
         file,
+        resolved,
     };
 }
 

package/engine/web-wikilinks.mjs

@@ -311,9 +311,17 @@ function isPlainMap(value) {
  * {@link module:engine/content-images.renderImageFigures} turns into a figure
  * for the website, and what the book reads its staging list out of.
  *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. That is the link
+ * graph, read at the one point where it exists: the build never has to walk a
+ * page a second time to learn what it links to. Nothing is recorded for a
+ * same-page anchor or for a target that resolved nowhere.
+ *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file, resolved }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
  *   `noIndexPackages` is every package declared `contentIndex: false`, so a
@@ -322,7 +330,8 @@ function isPlainMap(value) {
  *   is the cross-package manifest index; `assets` is the address space an embed
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
- *   stands in.
+ *   stands in. `resolved`, when supplied, is the array every resolved
+ *   target's index entry is appended to.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body, ctx) {
@@ -425,6 +434,8 @@ export function resolveWebWikilinks(body, ctx) {
                 lookupRead(ctx.foreign, read, ctx.contentPackage)
             :   undefined);
         if (hit) {
+            // The edge, for a caller reading the link graph off this pass.
+            ctx.resolved?.push(hit);
             // An address with an *empty* label has no prose to show (a
             // shortcode is not display text), so the document's **current**
             // name stands in and a rename shows at every citation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "22.4.3",
+    "version": "22.4.4",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — content compilation, manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",

package/types/engine/changelog-lint.d.mts

@@ -48,13 +48,15 @@ export function topLevelBullets(text: string, codeLines: Set<number>): Array<{
  * {@link topLevelBullets}, where a bullet marker *is* the top-level
  * construct — a `-` bullet at column 0 belongs to whatever block is
  * already open, since a label's bullets sit unindented directly under it.
- * Any other column-0 line (plain prose with no label, a bullet with no
- * block open yet) starts the one "lead" block (`label: null`) a changeset
- * with no category writes — the case `changelog group` sorts first and
- * `check` never flags. Nested detail — a wrapped line, a bullet's own
- * continuation — stays indented and belongs to whatever it follows.
- * `changelog group` folds same-label blocks together; `check` warns when a
- * block's label is not in the declared vocabulary.
+ * A plain column-0 line that is neither a label nor a bullet continues
+ * whatever block is open, because Prettier's `proseWrap` puts every line of
+ * a hard-wrapped paragraph at column 0 — it starts a new "lead" block
+ * (`label: null`) only at a paragraph boundary, the start of the section or
+ * a line right after a blank one, which is the case `changelog group`
+ * sorts first and `check` never flags. A blank line never closes a block by
+ * itself; it only ends the run of continuation lines a following column-0
+ * line can attach to. `changelog group` folds same-label blocks together;
+ * `check` warns when a block's label is not in the declared vocabulary.
  *
  * @param {string} text - Section text.
  * @param {Set<number>} codeLines - Lines inside a code region, from

package/types/engine/homepage.d.mts

@@ -148,15 +148,22 @@ export function homepageTitle(fm: object | null | undefined, config: object): st
  * redirect stub at each one. The field is retired and refused before a
  * build reaches here, which makes this a guard rather than a working path.
  *
+ * `related` is derived like every other page's — what links to the homepage
+ * is a fact about the rest of the tree — so an authored value is dropped and
+ * the caller's block, where it has one, is written in its place.
+ *
  * @param {object} fm - The note's frontmatter.
  * @param {object} options - Options.
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
+ * @param {object} [options.related] - The homepage's backlinks and mentions,
+ *   where the site build found either.
  * @returns {object} The frontmatter to write.
  */
-export function homepageFrontmatter(fm: object, { contentPackage, title }: {
+export function homepageFrontmatter(fm: object, { contentPackage, title, related }: {
     contentPackage: string;
     title: string;
+    related?: object | undefined;
 }): object;
 /**
  * Every address a homepage carries: the markdown links in its body.

package/types/engine/related-pages.d.mts

@@ -0,0 +1,70 @@
+/**
+ * Inverts a link graph into each page's backlinks and mentions.
+ *
+ * An edge is `(source URL, target URL)`, and a URL that is not in `entries` is
+ * not a page of this site, so an edge touching one is dropped. A self-link says
+ * nothing a reader is not already looking at, and a page that links another
+ * three times is connected to it once, so both collapse.
+ *
+ * The result holds only pages with at least one connection, so the caller can
+ * write nothing on a page with none — the theme's silent-disappear convention,
+ * kept at the source rather than papered over with an empty block.
+ *
+ * @param {Iterable<readonly [string, string]>} edges - Every resolved link, as
+ *   the source page's URL and the target page's.
+ * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
+ *   site, keyed by URL.
+ * @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: Iterable<readonly [string, string]>, entries: ReadonlyMap<string, RelatedEntry>): Map<string, Related>;
+/**
+ * The pages a homepage's body links to, as URLs.
+ *
+ * A homepage is published verbatim — no wikilink on it resolves, and its links
+ * are ordinary markdown the browser resolves against the page's own address,
+ * which is the package root. So its edges are read the same way: each target
+ * resolved against `base`, the way a browser would. A package-relative
+ * `being-x/`, a root-relative `/pkg/being-x/` and a `./being-x/#anchor` all
+ * name the same page; a bare `#anchor` names the homepage itself.
+ *
+ * A link that names a host or a scheme leaves the site, whatever path it
+ * carries, and yields nothing: the site's own pages are addressed without one.
+ *
+ * @param {string} body - The homepage's markdown body.
+ * @param {string} base - Where the package is served — the homepage's own URL.
+ * @returns {string[]} The targets' URLs, in body order, repeats included.
+ */
+export function homepageLinkTargets(body: string, base: string): string[];
+/**
+ * One entry in a `related` list — the page a reader is pointed at.
+ */
+export type RelatedEntry = {
+    /**
+     * The page's published title.
+     */
+    title: string;
+    /**
+     * `<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.
+     */
+    url: string;
+    /**
+     * The note's `type`, which the theme groups by.
+     */
+    type: string;
+};
+/**
+ * The `related` block one page publishes.
+ */
+export type Related = {
+    /**
+     * Pages that link to this one.
+     */
+    backlinks: RelatedEntry[];
+    /**
+     * Pages this one links to.
+     */
+    mentions: RelatedEntry[];
+};

package/types/engine/site-build.d.mts

@@ -65,14 +65,27 @@ export function collectHomepages(contentBase: string, ctx: object): {
  * states no `url` — the home kind has none to state — and the mount below it
  * holds pages and nothing else, so this is the only `_index.md` in the tree.
  *
+ * **Verbatim, but not unconnected.** The homepage is a page like any other on
+ * both sides of the link graph: a content page reaches it through
+ * `[[homepage-root|Text]]`, and its own markdown links name content pages. So
+ * it carries the same `related` block every content page does — handed in by
+ * the caller, since the graph is read off the content render and homepage-only
+ * mode has none.
+ *
  * @param {string} outRoot - The package's site root — the content mount's
  *   root, `build/hugo/content`, one level above the mount itself.
  * @param {readonly object[]} pages - From {@link collectHomepages}.
  * @param {object} config - The resolved configuration, for the package name and
  *   the default title.
+ * @param {object} [options] - Options.
+ * @param {import("./related-pages.mjs").Related} [options.related] - The
+ *   homepage's backlinks and mentions. Absent where nothing connects to it,
+ *   and in homepage-only mode, where no link resolves.
  * @returns {number} How many pages were written.
  */
-export function writeHomepages(outRoot: string, pages: readonly object[], config: object): number;
+export function writeHomepages(outRoot: string, pages: readonly object[], config: object, { related }?: {
+    related?: import("./related-pages.mjs").Related | undefined;
+}): number;
 /**
  * The integrity gates a site build runs before it writes anything.
  *
@@ -159,6 +172,12 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * self-describing and makes sweeping the field out of a content tree
  * output-preserving for a site as it already is for the packs.
  *
+ * **`related` is derived, never authored.** What links to a page is a fact
+ * about every other page, known only once the whole tree has resolved — see
+ * {@link module:engine/related-pages} — so an authored value is dropped the
+ * way `aliases` is, and {@link renderPages} writes the derived block once it
+ * holds the graph.
+ *
  * @param {object} page - The page.
  * @param {object} options
  * @param {(data: object, page: object) => void} [options.decorate] - Called
@@ -210,10 +229,23 @@ export function pageDestination(page: object): string;
  *    touches, so the repository's own rewrite runs before the shared one
  *    rather than replacing it.
  *
+ * **Every page is rendered before any is written.** What links *to* a page is
+ * known only once every other page has resolved, and it is written into the
+ * page's own front matter, so the render is one pass over the tree and the
+ * write is a second — with the link graph read off the first, at the one
+ * point the resolver answers, and inverted once between them. Nothing is
+ * resolved twice.
+ *
  * @param {object[]} pages - Every page.
- * @param {object} options - Everything the render needs.
+ * @param {object} options - Everything the render needs. `homepages` is the
+ *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
+ *   no part in the render and every part in the graph: a content page links
+ *   it by wikilink, and its own markdown links name content pages.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[]}}
+ *   wikiErrors: object[], imageErrors: object[],
+ *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   is keyed by page URL, and holds the homepage's block beside every content
+ *   page's, so the caller can write it on the page this render does not.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -221,6 +253,7 @@ export function renderPages(pages: object[], options: object): {
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    related: Map<string, import("./related-pages.mjs").Related>;
 };
 /**
  * Resolves `site.pass` to its bundle.

package/types/engine/site-index.d.mts

@@ -41,6 +41,9 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
  *   resolvers that distinguish a foreign hit from a local one.
  * @param {object} [options.assets] - The address space an `![[…]]` embed
  *   resolves against, shaped as every asset resolver reads one.
+ * @param {object[]} [options.resolved] - Collector the resolver appends every
+ *   resolved target's index entry to — the page's outbound edges, read off
+ *   the one pass that resolves them.
  * @returns {object} The resolver context.
  *
  * There is deliberately **no `manifestsComplete`**. It used to let a resolver
@@ -49,13 +52,14 @@ export function buildSiteIndex(entries: readonly SiteEntry[], { foreignIndex, no
  * checker never had it and one authored link must not get two verdicts. A
  * caller still passing it is ignored rather than obeyed.
  */
-export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets }: {
+export function wikiContext(built: SiteIndex, { src, file, type, errors, foreignIndex, assets, resolved }: {
     src: string;
     type?: string | null | undefined;
     errors: object[];
     file?: string | undefined;
     foreignIndex?: Map<string, object> | undefined;
     assets?: object | undefined;
+    resolved?: object[] | undefined;
 }): object;
 /**
  * Resolve one infobox reference against a site index.

package/types/engine/web-wikilinks.d.mts

@@ -76,9 +76,17 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  * {@link module:engine/content-images.renderImageFigures} turns into a figure
  * for the website, and what the book reads its staging list out of.
  *
+ * ## Every hit is recorded, so the page's edges come out of one pass
+ *
+ * A caller that hands in `ctx.resolved` is given every index entry a link on
+ * the page resolved to, in body order, repeats included. That is the link
+ * graph, read at the one point where it exists: the build never has to walk a
+ * page a second time to learn what it links to. Nothing is recorded for a
+ * same-page anchor or for a target that resolved nowhere.
+ *
  * @param {string} body - The markdown body.
  * @param {object} ctx - `{ index, assets, collide, contentTypes,
- *   packages, noIndexPackages, foreign, type, errors, src, file }`.
+ *   packages, noIndexPackages, foreign, type, errors, src, file, resolved }`.
  *   `packages` is every package an address may name, without which the leading
  *   package segment of a canonical address reads as an unknown type;
  *   `noIndexPackages` is every package declared `contentIndex: false`, so a
@@ -87,7 +95,8 @@ export function frontmatterWikilinks(fm: unknown): Array<{
  *   is the cross-package manifest index; `assets` is the address space an embed
  *   resolves against. `src` is the page's display
  *   path and `file` the source file a diagnostic should name — absent, `src`
- *   stands in.
+ *   stands in. `resolved`, when supplied, is the array every resolved
+ *   target's index entry is appended to.
  * @returns {string} The body with embeds and wikilinks rewritten.
  */
 export function resolveWebWikilinks(body: string, ctx: object): string;