@heroiclands/package-build 22.20.0 → 22.22.0

package/CHANGELOG-content-build.md

@@ -62,7 +62,6 @@
   pass, which reads them exactly as it reads a local pack.
 
   Three things it does deliberately:
-
   - **Pins, rather than following `latest`.** A published
     `releases/latest/download/…` URL is rewritten to the declared
     `compatibility.verified` version, so a build names one particular dependency
@@ -177,7 +176,6 @@
 
   `content-build lint` now checks frontmatter as well as addresses. Five classes,
   each previously reported somewhere other than where it was made, or not at all:
-
   - **Unknown or retired type**, told what replaced it.
   - **Missing required property** — `dimensions` on a map, `subType` on a skill.
   - **Wrong value shape** — `weight: heavy` where a number belongs.
@@ -215,7 +213,6 @@
   configures (#69).
 
   Two new commands:
-
   - `content-build format [paths..] [--write]` — Prettier, with the shared
     configuration.
   - `content-build markdown [paths..] [--fix]` — markdownlint, with a narrow,
@@ -310,7 +307,6 @@ version` regenerates it in every repository here.
   entries) exactly as the scripts it replaces emit them, on the same toolchain.
 
   Also new:
-
   - `paths.manifestOut` (default `build/manifests`) — where the manifest is
     written. Deliberately not `paths.manifests`, which is the _inbound_ directory
     of vendored foreign manifests that `links` consumes.
@@ -377,7 +373,6 @@ compile`. Publishing the _same tree_ as a website was a script each consumer
   exotic, so neither is left to care.
 
   Also new:
-
   - `engine/site-build.mjs` exports each stage (`collectContentPages`,
     `collectTreePages`, `siteGates`, `renderPages`, `writeSectionLandings`) for a
     consumer that needs a step rather than the whole command.
@@ -422,7 +417,6 @@ compile`. Publishing the _same tree_ as a website was a script each consumer
   stale by `--check` on every clean checkout — the two undoing each other forever.
   Three things were making that happen, and all three are fixed at the source
   rather than by adding a formatting pass:
-
   - Table columns are padded to their widest cell, which is what Prettier's
     alignment comes to for this content.
   - The worked example's fence said `yaml`, but the block is a whole note —
@@ -632,7 +626,6 @@ compile`. Publishing the _same tree_ as a website was a script each consumer
   hide the next drift instead of surfacing it.
 
   Two deliberate differences from the code it replaces:
-
   - **The `corpus` derivation is dropped.** `corpus` is not a registered item
     type, so nothing can compile to one and the branch matched nothing — the same
     class of dead code as the gate that caused the bug. It was in SoHL's copy and
@@ -654,7 +647,6 @@ compile`. Publishing the _same tree_ as a website was a script each consumer
   `gh release create`, because cutting the Release is what published. Nothing
   enforced the last step, so on 2026-08-21 `main` carried 0.5.1 while npm served
   0.4.0: two versions merged and never published, with no check red.
-
   - Every pull request now declares its bump as a `.changeset/*.md` file, and CI's
     **Changeset declared** job fails one that does not. `npx changeset add --empty`
     is how a change says it needs no release — explicitly, rather than by omission.

package/CHANGELOG.md

@@ -1,5 +1,209 @@
 # @heroiclands/package-build
 
+## 22.22.0
+
+### Minor Changes
+
+**Diagnostics**
+
+- A dead `#anchor` now fails the website build, matching the compendium build
+  and the link checker — a link that used to publish a dead section quietly now
+  reports it.
+- A note with more than one problem in its body now reports every one of them
+  in a single build, instead of only the first.
+
+**The book**
+
+- A page link in a book now goes where it says, and one into a package the book
+  depends on reaches that package's pages; the address they are built from is
+  `package.json`'s `homepage`, which a book now needs.
+- A note written for the next author — a `markdownlint` pragma, an aside about a
+  quoted notice — no longer appears on the page.
+- A box written inside a GM-only section prints as a box.
+- A box's title prints as written, emphasis included, and one carrying a bracket,
+  a `#` or a `$` no longer stops the book being made.
+- Two captions sharing one id each print their own block once, under their own
+  number.
+- A link that resolves nowhere now fails the book build, as it already fails the
+  compendium and website builds, and the book is still written so the page
+  carrying the link can be found.
+- Markup the book cannot set is reported at the file and line it is written on
+  rather than printed on the page, in a title page and a prose file as well as in
+  a note.
+- A table query that selects no rows now says so, and names the line, where it
+  read `[object Object]`.
+- A link the book cannot resolve names the line and column it is written on.
+
+**Affiliations**
+
+- A rank with no title or no description is now reported instead of shipping, so
+  a member's standing can no longer resolve to a blank on a sheet or a page.
+- A rank level that is not a whole number, and a key a rank does not take, are
+  reported too, each naming the line the rank is written on.
+- Every problem on one rank is reported at once, so a ladder is fixed in a single
+  pass.
+- A rank needs only its level, title and description; the lore note is for a
+  standing that needs more said about it than a description can hold.
+- An affiliation's rank ladder now appears on its page, alongside its offices,
+  ordered by level.
+- A note's `lore`, `parents`, `domains` and `economy` lists now reach the page
+  wherever they are authored, instead of vanishing silently.
+- A being's entry in a body states the rung it stands on — an ordinary member is
+  1, someone cast out is 0 — and an entry that states none is reported.
+- An office is not a rung, so an entry naming a post and no standing is reported
+  with the rest of them.
+- A body that gives two rungs one level is reported on the second, so what a
+  standing is called does not depend on which rung is written first.
+
+**Authoring**
+
+- A note's frontmatter accepts only the documented keys; an unrecognised one is an error at its own line, naming every accepted key and the one it was probably meant to be.
+- A page takes its heading from the note's name, so a homepage stating a title any other way publishes the name its package manifest carries.
+- Active Effects and document flags are read from the game-system block that carries them, so a note stating either outside one ships a document without them.
+- Info boxes, warning boxes and captions can be written again: any note using
+  one failed its build with an error about a secret block it did not contain.
+- A note may now mix boxes, captions and GM-only sections freely, and a box
+  inside a GM-only section stays inside it.
+- A `:::` line that closes nothing says so plainly instead of naming the wrong
+  construct.
+- An image may be sized `full-width`, and a float takes a named corner — both
+  always worked and neither was written down.
+
+**Beings**
+
+- A being's complexion can now hold several values, because a face is weathered
+  and ruddy at once rather than only one of them.
+- Several of them read as one phrase on a sheet or a page — "weathered, ruddy and
+  scarred complexion" — rather than saying the word once per value.
+- A being may be recorded as `nonbinary`, or as having no gender at all, where
+  before only `male`, `female` and `other` were named.
+- A frame is `scant`, `light`, `medium`, `heavy` or `massive`. The reference named
+  a `heavy` frame `large`, which nothing wrote.
+- A being's body and movement are authored under `sohl.system`, and its
+  attributes and skills as `sohl.items` entries; a note writing either
+  elsewhere in the block is reported.
+
+**Actors**
+
+- An `{#appearance}` or `{#dossier}` anchor written on a heading below the top
+  level now fails the build naming the file and the line, instead of compiling
+  a blank appearance or biography with nothing to say why.
+
+**Dates**
+
+- A birth or death date written without quotes is reported where a day's
+  trailing zero could have been lost, naming both days the value could mean. A
+  calendar's epoch and a moon's new day read the same way.
+
+**Definition lists**
+
+- Every package now ships a definition-list style, so a term and its definition
+  line up in two columns with the terms sharing one right edge.
+- A narrow journal window stacks each term above its own definition instead of
+  cramping both into columns, and widening the window restores them.
+- A term is bold wherever it appears, so writing one needs no `**` around it.
+- Infobox rows in the book sit against the same right edge, with space between
+  rows rather than run together.
+
+**Packages**
+
+- `packageBuild.baseStyles: false` declines the shared style for a package that
+  wants the surface entirely to itself.
+
+**Named blocks**
+
+- A `:::secret`, `:::info` or `:::warn` block now takes a title of its own, so a
+  GM passage can say "For the GM" or "If they ask about the harbour" instead of
+  one fixed word.
+- A block also takes an id, classes and other attributes, so a note can link to
+  one and a package can style a particular kind its own way.
+- Without a title a block heads itself **Secret**, **Info** or **Warn**. A
+  warning that used to head "Warning" now heads "Warn", and a secret that used to
+  head "GM note" now heads "Secret"; writing `title="GM note"` keeps the old
+  wording.
+- A secret on a web page now opens with its own title rather than the word
+  "Spoiler", and carries its kind so a site can style it.
+- A block's colours come from a stylesheet rather than from the block itself,
+  so a light panel no longer keeps a light background against dark page text.
+- A misspelled block name is now reported instead of being left in the page as
+  the literal `:::name` an author typed.
+- One malformed block no longer stops every other block in the same note from
+  rendering.
+- A box written inside a GM-only section stays inside it, and a box inside
+  another box says so rather than rendering as a muddle.
+
+**Configuration**
+
+- A `compatibility.verified` build below the package's own `compatibility.minimum`
+  is now reported instead of shipping a manifest that claims a build was verified
+  against a floor it cannot install on.
+- The same check applies to a declared system's and a related package's own
+  `compatibility`, naming the file and line of the offending `verified`.
+
+### Patch Changes
+
+**Lists**
+
+- A list item opened with `- [ ]` or `- [x]` reads as its own words everywhere
+  — on the website, in the compendium, and in the book — never as a checkbox.
+- Writing one that way is reported at its own line, naming the ordinary list
+  it belongs in.
+
+**Footnotes**
+
+- A footnote referenced inside a box or a caption now prints and numbers with
+  the rest of the note instead of showing as literal text.
+- A definition written below the top level of a note is reported, as is a
+  reference nothing defines.
+- A definition no reference uses is reported rather than dropped from the page.
+
+**Named blocks and captions**
+
+- A heading that would open a page of its own is reported when it is written
+  inside a box or a caption.
+
+**Headings**
+
+- A heading carrying classes or attributes beside its anchor now anchors on the
+  anchor alone, so a link written to it resolves on every surface.
+- A Foundry journal and a web page carry a heading's classes and attributes onto
+  the heading, and no surface prints the braces.
+- A heading whose braces hold something other than an attribute block is
+  reported at its own line instead of being typeset.
+- `.secret` on the heading that opens a section makes its Foundry page the
+  GM's alone.
+- A withheld section reads as a spoiler on the web and a labelled block in the
+  book, which conceal it rather than withhold it.
+- A heading refuses `id=`, `class=` and any key beginning `on`, as a named block
+  does, so no note writes an event handler onto a page.
+
+**Page lists**
+
+- A note can now write a page list: name a tag, and the pages carrying it come out as a list of links.
+- The list reaches a reader in Foundry, on the website and in the book alike, from the one directive.
+- A page joins the list by carrying its tag and leaves by losing it, so a landing page stays true as notes are written.
+- A list can print each page's description beside its link, and can be restricted to one note type.
+- A tag that no page carries is reported with the tag it looked for, rather than printing nothing.
+
+**Beings**
+
+- A being's `socialTies` map now builds without the two findings it always
+  produced, so a patron, friend, dependent, acquaintance, rival or nemesis
+  can be written.
+
+## 22.21.0
+
+### Minor Changes
+
+**Standing in a body** — A being's `affiliations` is now a map keyed by the body, and each entry says what the being is there: `rank`, a level on that body's own ladder, and `office`, one of the posts it names. A page prints the standing closing on the body it belongs to — "War Chief, Hárár, of Vrystwald Tribes" — and an office links to the description the body already carries. In SoHL a being now arrives carrying one affiliation item per body it belongs to, standing included.
+
+**Offices read the right way round** — An affiliation's offices each take their own row, with the post's name as the label and its description beside it, and each row can be linked to directly.
+
+### Patch Changes
+
+- Icons drawn with outlines follow the colour scheme instead of keeping a black rim in dark mode.
+- An explicitly black outline also moves to ink in light mode, matching the icon's filled shapes.
+
 ## 22.20.0
 
 ### Minor Changes

package/assets/styles/content-base.css

@@ -0,0 +1,162 @@
+/*
+ * 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
+ */
+
+/*
+ * The base stylesheet every package ships, staged into the package root and
+ * named first in the manifest's `styles`.
+ *
+ * It carries only what every package needs for its compiled content to be
+ * legible, which today is the definition list: an infobox emits one, and so
+ * does the ordinary markdown `Term` / `: definition` syntax. A package keeps
+ * its own stylesheet for its own needs and overrides anything here from it.
+ *
+ * `packageBuild.baseStyles: false` declines it.
+ *
+ * **The scope is the content, not the interface.** Foundry styles `dl dt` and
+ * `dl dd` itself, application-wide, and a package stylesheet loads into a later
+ * cascade layer than those rules sit in — so an unscoped `dl` here would
+ * restyle every definition list in Foundry's own chrome and in every other
+ * package's sheets. The four roots are where compiled content renders: a
+ * journal page, a journal entry, an enriched field, and the editor.
+ */
+
+/*
+ * Definition lists, in two states of one style.
+ *
+ * **Wide.** Two columns, the term right-aligned against a fixed gutter so every
+ * term in the list shares one right edge, the definition in the remaining
+ * space. The fixed track is what produces the shared edge; a `max-content`
+ * track cannot, because each row then sizes itself.
+ *
+ * **Narrow.** Stacked, the term above its own definition, with space between
+ * pairs and none between a term and the definition it belongs to.
+ *
+ * **The measurement is the list, not the screen.** A Foundry journal is a
+ * resizable window, usually far narrower than the viewport, so a viewport media
+ * query would hold a journal stacked while the screen said otherwise — or cramp
+ * it into two columns at 300px. `container-type: inline-size` on the `dl` and a
+ * `@container` query on its children measure the list itself, and give the same
+ * two states on a page, in a window and in a sidebar.
+ *
+ * The narrow state is reached by spanning both tracks rather than by changing
+ * the template, because an element cannot query the container it establishes:
+ * the `dl` holds the grid and the container, so only `dt` and `dd` can respond.
+ * Row spacing is the definition's bottom margin rather than the grid's
+ * `row-gap` for the same reason — `row-gap` sits on the `dl`, and the two
+ * states need different values.
+ *
+ * The three tunable values are custom properties, so a package adjusts the term
+ * column, the gutter or the stacking point without copying the rule.
+ */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) dl {
+    display: grid;
+    /* `minmax(0, …)` keeps the track at its full width wherever there is room
+     * and lets it shrink rather than overflow where there is not. */
+    grid-template-columns: minmax(0, var(--pb-deflist-term-width, 11rem)) 1fr;
+    column-gap: var(--pb-deflist-gutter, 2rem);
+    container-type: inline-size;
+    container-name: pb-deflist;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) dl > dt {
+    grid-column: 1;
+    /* The one rule that holds on every surface, so an author writes the term
+     * and nothing else rather than bolding it by hand. */
+    font-weight: 600;
+    text-align: right;
+    line-height: 1.6;
+    margin: 0;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) dl > dd {
+    grid-column: 2;
+    margin: 0 0 var(--pb-deflist-row-gap, 1.5rem);
+    line-height: 1.6;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) dl > dd:last-child {
+    margin-bottom: 0;
+}
+
+/*
+ * Stacked, below the width two columns need: the term column, the gutter, and
+ * enough left for a definition to read as prose rather than as a word per line.
+ *
+ * Named, so the query resolves against a list this sheet set up rather than
+ * against whichever ancestor container happens to be nearest.
+ */
+@container pb-deflist (max-width: 32rem) {
+    dt {
+        grid-column: 1 / -1;
+        text-align: left;
+    }
+
+    dd {
+        grid-column: 1 / -1;
+    }
+}
+
+/*
+ * Named body blocks. `:::info` and `:::warn` emit a `<section>` carrying the
+ * block's name as its class, so the appearance belongs here rather than in an
+ * inline `style` a consumer cannot override.
+ *
+ * `secret` is deliberately absent: Foundry styles `section.secret` itself and
+ * owns the reveal control on it, and a rule here would fight both.
+ *
+ * Every colour is a custom property, so a package overrides one from its own
+ * sheet without restating the layout.
+ */
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    :is(section.info, section.warn) {
+    border-left: 3px solid var(--pb-block-edge);
+    background: var(--pb-block-fill);
+    color: var(--pb-block-text, inherit);
+    padding: 0.5em 0.8em;
+    margin: 0.75em 0;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+    :is(section.info, section.warn)
+    > strong:first-child {
+    color: var(--pb-block-edge);
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) section.info {
+    --pb-block-edge: #2f6f9f;
+    --pb-block-fill: #eef6fb;
+}
+
+:is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) section.warn {
+    --pb-block-edge: #9a6700;
+    --pb-block-fill: #fff5db;
+}
+
+/*
+ * A light panel keeps a dark foreground whatever the surrounding theme does to
+ * the inherited colour, because the fill does not follow it.
+ */
+@media (prefers-color-scheme: dark) {
+    :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror)
+        :is(section.info, section.warn) {
+        --pb-block-text: #1b1b1b;
+    }
+
+    :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) section.info {
+        --pb-block-edge: #1d4f75;
+    }
+
+    :is(.journal-entry-page, .journal-entry-content, .editor-content, .prosemirror) section.warn {
+        --pb-block-edge: #7a5100;
+    }
+}

package/bin/content-commands.mjs

@@ -70,6 +70,7 @@ import { lintContentCharset } from "../engine/content-charset.mjs";
 import { lintContentHtml } from "../engine/content-html.mjs";
 import { lintContentIcons } from "../engine/content-icons.mjs";
 import { lintContentImages } from "../engine/content-images.mjs";
+import { lintContentTaskLists } from "../engine/content-tasklists.mjs";
 import {
     declaredSystems,
     lintFrontmatter,
@@ -1156,6 +1157,13 @@ function lintCommand() {
                     config,
                 });
 
+                // A list item opened with `[ ]` or `[x]` — nothing here is
+                // miscompiled, since every surface sets the marker as the
+                // item's own text and all three agree, so this is advisory.
+                const taskLists = lintContentTaskLists(root, {
+                    skipDirectories: config.skipDirectories,
+                });
+
                 // Whether every empty body is a stub on purpose, and how
                 // finished the tree is. The counts and the oldest drafts are
                 // prose rather than findings: a note nobody has finished is not
@@ -1175,6 +1183,7 @@ function lintCommand() {
                     ...icons.findings,
                     ...html.findings,
                     ...images.findings,
+                    ...taskLists.findings,
                     ...states.findings,
                 ];
                 // Only an **error** fails the run. Every finding was an error
@@ -1461,14 +1470,20 @@ function linksCommand() {
                     }),
                 );
 
+                // Worded by the shared table, like every finding below it: a
+                // sentence written here is free to describe the same defect
+                // differently from the build that also refuses it, which is the
+                // drift the table exists to prevent.
                 for (const d of deadAnchors) {
                     emitDiagnostic({
                         file: d.note.file,
                         ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
                         severity: "error",
-                        message:
-                            `link [[${d.link}]] points at an anchor no ` +
-                            `heading in ${d.dest.rel} declares`,
+                        message: linkFindingMessage({
+                            reason: "unknown-anchor",
+                            target: d.target,
+                            anchor: d.anchor,
+                        }),
                     });
                 }
                 // Every link is an address and every address must
@@ -1799,6 +1814,12 @@ function siteCommand() {
                 for (const e of result.captionErrors) {
                     emitDiagnostic({ ...e, severity: "error" });
                 }
+                for (const e of result.headingErrors) {
+                    emitDiagnostic({ ...e, severity: "error" });
+                }
+                for (const e of result.footnoteErrors) {
+                    emitDiagnostic({ ...e, severity: "error" });
+                }
                 // Reported the way the pack build reports the very same
                 // finding: `file:line:column: error: message`, path first, and
                 // the message from the shared table, not a
@@ -1838,6 +1859,8 @@ function siteCommand() {
                     result.expressionErrors.length ||
                     result.secretErrors.length ||
                     result.captionErrors.length ||
+                    result.headingErrors.length ||
+                    result.footnoteErrors.length ||
                     result.wikiErrors.length ||
                     result.imageErrors.length
                 ) {

package/bin/package-build.mjs

@@ -93,6 +93,7 @@ import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath, resolveConfigFile } from "../engine/pack-config.mjs";
 import { cleanBuildArtifacts, resetStage, stageAssets } from "../stage.mjs";
+import { baseStyleStageEntry } from "../engine/base-styles.mjs";
 import { buildSchemaArtifact } from "../engine/schema-extract.mjs";
 import { emitCalendarArtifacts } from "../engine/calendar-artifacts.mjs";
 import { dateFromCalendar, dateToCalendar } from "../engine/date-conversion.mjs";
@@ -424,7 +425,7 @@ function assetsCommand() {
         builder: (y) => y,
         handler: handler(async () => {
             const config = loadPackageBuildConfig();
-            if (!config.assets.length) {
+            if (!config.assets.length && !config.baseStyles) {
                 console.log("package-build: no `packageBuild.assets` declared; nothing to stage.");
                 return;
             }
@@ -462,10 +463,22 @@ function assetsCommand() {
                 from,
                 path.join(config.stageDir, to),
             ]);
-            const { entries: count, files } = stageAssets(entries, {
+            let { entries: count, files } = stageAssets(entries, {
                 cwd: config.rootDir,
                 transform,
             });
+
+            // Staged in its own pass, without the repository's transform: the
+            // sheet is this toolchain's file rather than one of the
+            // repository's assets, and a `transform` written to retheme a
+            // package's own SVGs has no business being handed it.
+            if (config.baseStyles) {
+                const staged = stageAssets([baseStyleStageEntry(config.stageDir)], {
+                    cwd: config.rootDir,
+                });
+                count += staged.entries;
+                files += staged.files;
+            }
             console.log(`✅ Static assets staged (${count} entries, ${files} files).`);
         }),
     };

package/ci/content-format-reference.mjs

@@ -9,9 +9,12 @@ import { formatGenerated } from "../engine/format-generated.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     BEING_ARCHETYPES,
+    NOTE_TOP_LEVEL_FIELDS,
     NOTE_VOCABULARY,
     SHARED_DATA_FIELDS,
 } from "../engine/note-vocabulary.mjs";
+import { EXPRESSION_HELPERS } from "../engine/markdown-expressions.mjs";
+import { PAGE_LIST_ATTRIBUTES } from "../engine/page-lists.mjs";
 
 const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const output = path.join(root, "docs/reference/note-types.md");
@@ -39,6 +42,16 @@ const rows = [
     "",
     "The [first-note guide](../authoring/first-note.md) teaches the shape of a note. [Frontmatter](../authoring/frontmatter.md) explains shared and system-specific values. The [detailed reference](format-details.md) gives the full behavior and examples.",
     "",
+    "## Top-level keys",
+    "",
+    "These are the only keys a note writes at its top level, in the order the formatter puts them. A key absent from this table is a lint error at its own line: the region is closed, so the key reaches no document and no page. Facts about the subject belong under `data`, and values for one game system belong inside that system's block.",
+    "",
+    "| Key | Meaning |",
+    "| --- | --- |",
+    ...NOTE_TOP_LEVEL_FIELDS.map(
+        (field) => `| \`${cell(field.name)}\` | ${cell(field.describe)} |`,
+    ),
+    "",
     "## Shared `data` fields",
     "",
     "These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.",
@@ -106,7 +119,61 @@ if (process.argv.includes("--check")) {
         process.exitCode = 1;
     }
 } else {
-    process.stdout.write(result);
+    fs.writeFileSync(output, result);
+}
+
+// The two tables `docs/authoring/links-and-markup.md` generates: every helper
+// an expression may call, and every attribute a page-list fence takes. Both are
+// written from the one list the engine reads, so neither document can fall
+// behind a new entry. Replaced in one pass and written once, so a `--check` run
+// names the file rather than one of the tables in it.
+const markupPath = path.join(root, "docs/authoring/links-and-markup.md");
+const markup = fs.readFileSync(markupPath, "utf8");
+const GENERATED_TABLES = [
+    {
+        marker: "expression-helpers",
+        rows: [
+            "| Helper | Parameters | What it gives you |",
+            "| ------ | ---------- | ----------------- |",
+            ...Object.entries(EXPRESSION_HELPERS).map(
+                ([name, { params, summary }]) =>
+                    `| \`${name}\` | \`${params}\` | ${cell(summary)} |`,
+            ),
+        ],
+    },
+    {
+        marker: "page-list-attributes",
+        rows: [
+            "| Attribute | Value | Default | What it does |",
+            "| --------- | ----- | ------- | ------------ |",
+            ...Object.entries(PAGE_LIST_ATTRIBUTES).map(
+                ([name, { value, default: fallback, summary }]) =>
+                    `| \`${name}\` | ${cell(value)} | ${cell(fallback)} | ${cell(summary)} |`,
+            ),
+        ],
+    },
+];
+let markupBody = markup;
+for (const { marker, rows } of GENERATED_TABLES) {
+    const region = new RegExp(`<!-- ${marker}:start -->[\\s\\S]*?<!-- ${marker}:end -->`);
+    if (!region.test(markupBody)) {
+        throw new Error(`The ${marker} reference requires its generation markers`);
+    }
+    markupBody = markupBody.replace(
+        region,
+        `<!-- ${marker}:start -->\n\n${rows.join("\n")}\n\n<!-- ${marker}:end -->`,
+    );
+}
+const updatedMarkup = await formatGenerated(markupBody, markupPath);
+if (process.argv.includes("--check")) {
+    if (markup !== updatedMarkup) {
+        console.error(
+            "docs/authoring/links-and-markup.md: error: run node ci/content-format-reference.mjs to refresh its generated tables",
+        );
+        process.exitCode = 1;
+    }
+} else {
+    fs.writeFileSync(markupPath, updatedMarkup);
 }
 
 const detailsPath = path.join(root, "docs/reference/format-details.md");