@heroiclands/package-build 22.2.0 → 22.3.1

package/docs/configuration.md

@@ -727,11 +727,12 @@ How this repository frames the documentation pages it generates.
 registry and are the same wherever rendered; everything here is the
 consumer's: heading, orientation, where the page is filed.
 
-| Key                        | Type     | Required | Default                                                                |
-| -------------------------- | -------- | -------- | ---------------------------------------------------------------------- |
-| `docs.itemFields.title`    | string   | no       | none — the page's H1                                                   |
-| `docs.itemFields.out`      | string   | no       | none — without it, the page goes to stdout                             |
-| `docs.itemFields.preamble` | string[] | no       | none — markdown lines between the generated banner and the first table |
+| Key                           | Type     | Required | Default                                                                |
+| ----------------------------- | -------- | -------- | ---------------------------------------------------------------------- |
+| `docs.itemFields.title`       | string   | no       | none — the page's H1                                                   |
+| `docs.itemFields.out`         | string   | no       | none — without it, the page goes to stdout                             |
+| `docs.itemFields.preamble`    | string[] | no       | none — markdown lines between the generated banner and the first table |
+| `docs.itemFields.frontmatter` | object   | no       | none — extra note frontmatter, deep-merged over the generated envelope |
 
 > ``package-build config: `docs.itemFields` must be a mapping.``
 
@@ -744,9 +745,14 @@ consumer's: heading, orientation, where the page is filed.
 
 > ``package-build config: `docs.itemFields.preamble[<index>]` must be a string.``
 
+`frontmatter` is deep-merged over the note envelope written when `out` is
+under the content tree — see [`content-build docs item-fields`](commands.md#content-build-docs-item-fields):
+
+> ``package-build config: `docs.itemFields.frontmatter` must be a mapping.``
+
 Any other key under `docs.itemFields` is refused:
 
-> ``package-build config: `docs.itemFields.<key>` is not a recognized option (expected one of: title, out, preamble).``
+> ``package-build config: `docs.itemFields.<key>` is not a recognized option (expected one of: title, out, preamble, frontmatter).``
 
 ### `site`
 
@@ -759,9 +765,7 @@ Any other key under `docs.itemFields` is refused:
 | `site.description`      | string   | `""`, but required for `content-build site` |
 | `site.packages`         | string[] | `[]`                                        |
 | `site.sections`         | object   | `{}`                                        |
-| `site.readmeSections`   | object   | `{}`                                        |
 | `site.landing`          | object   | `null`                                      |
-| `site.trees`            | array    | `[]`                                        |
 | `site.pass`             | string   | `""`                                        |
 | `site.passOptions`      | object   | `{}`                                        |
 | `site.backfillSections` | boolean  | `false`                                     |
@@ -771,10 +775,19 @@ Any other key under `docs.itemFields` is refused:
 
 How much of a package reaches the web at all is **not** here — it is
 [`publish.site`](#publish). `site` is framing: what a section is called,
-which extra trees are published beside the content, which named pass bundle
-supplies the repository's own body rewrites, and the residue of the
-[generated Hugo configuration](#the-generated-hugo-configuration) that is
-genuinely this repository's own.
+which named pass bundle supplies the repository's own body rewrites, and the
+residue of the [generated Hugo configuration](#the-generated-hugo-configuration)
+that is genuinely this repository's own.
+
+What the site publishes is the content tree, and nothing beside it. A page of
+documentation is a note — `type: doc`, addressed by its shortcode, and
+`pack: none` where it compiles into no Foundry document — so there is no
+second mechanism for mounting a directory of markdown, and a configuration
+that names one is refused with a message saying where the page goes instead:
+
+> ``package-build config: `site.trees` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and declare the section that lists it under `site.sections`.``
+
+> ``package-build config: `site.readmeSections` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and declare the section that lists it under `site.sections`.``
 
 Where the Hugo tree is written is not a choice. `content-build site` writes
 the whole Hugo source tree under `build/hugo/` — the generated `hugo.toml`,
@@ -786,7 +799,7 @@ published. A `site.out` is refused by name:
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, sections, readmeSections, landing, trees, pass, passOptions, backfillSections, list, notfound, hugo).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, sections, landing, pass, passOptions, backfillSections, list, notfound, hugo).``
 
 `site.assets` is the host every package's imagery is served from, and it is
 the one address in this file that is not this repository's own. A note names
@@ -832,25 +845,8 @@ names a registry):
 
 > ``package-build config: `site.packages[<index>]` must be a non-empty string.``
 
-`site.trees` are the extra trees published beside the content, each naming
-where it comes from and which section it publishes into:
-
-| Key (under `site.trees[]`) | Type   | Required |
-| -------------------------- | ------ | -------- |
-| `site.trees[].from`        | string | yes      |
-| `site.trees[].section`     | string | yes      |
-
-> ``package-build config: `site.trees` must be a list.``
-
-> ``package-build config: `site.trees[<index>]` must be a mapping.``
-
-> ``package-build config: `site.trees[<index>].from` must be a non-empty string.``
-
-> ``package-build config: `site.trees[<index>].<key>` is not a recognized option (expected one of: from, section).``
-
-`site.sections` (and `site.readmeSections`, the same shape) is a closed
-vocabulary — a section's _only_ place to speak, since it exists solely as
-the generated `_index.md` this build writes for it:
+`site.sections` is a closed vocabulary — a section's _only_ place to speak,
+since it exists solely as the generated `_index.md` this build writes for it:
 
 | Key (under `site.sections.<name>`) | Type                       | Required | Default |
 | ---------------------------------- | -------------------------- | -------- | ------- |
@@ -1336,9 +1332,9 @@ its content tree's addresses mount inside the package.
 Every HeroicLands package publishes at least an authored homepage at
 `https://www.heroiclands.org/<contentPackage>/` — there is no value meaning
 _no web presence at all_. `homepage` is the floor: the authored homepage
-and nothing else, no content-tree walk, no `site.sections` / `site.trees` /
-`site.landing` output. `content` is the homepage plus every page the
-content tree publishes. `publishesContentPages(config)`, exported from
+and nothing else, no content-tree walk, no `site.sections` / `site.landing`
+output. `content` is the homepage plus every page the content tree
+publishes. `publishesContentPages(config)`, exported from
 `content-config.mjs` alongside [`compilesFoundryDocuments`](#packagekind),
 answers the one question every reader of the mode actually asks — the site
 build, to decide whether to walk the tree at all, and the content index, to

package/docs/content-format.md

@@ -801,13 +801,43 @@ hm3:
 Where no pack of that type is the default, the build refuses rather than
 guessing, and names the candidates.
 
-Three declarations are refused, each with the reason:
+**`pack: none` compiles the note into no document.** The note is walked,
+published as a page, present in the content index with an address and no
+Foundry UUID, and addressable by wikilink like any other; every pack compiler
+passes over it without a finding, and the check that reports a note nothing
+compiles says nothing about it. Write it on a page that belongs on the website
+and in no compendium — a page of developer documentation, a page about the
+package itself:
 
-| written                             | why it is refused                                                                 |
-| ----------------------------------- | --------------------------------------------------------------------------------- |
-| a **companion** pack                | A companion is written by another pack's pass, so no note may be routed into one. |
-| a pack **nothing answers to**       | The message lists the configured packs of that document type.                     |
-| a pack of **another document type** | A note's `pack:` names a pack of its own document type.                           |
+```yaml
+type: doc
+subType: concept
+shortcode: architecture
+pack: none
+```
+
+A link to such a note resolves everywhere the note is addressable. On the web
+it is an ordinary link to the page. In a compiled journal there is no document
+to open, so the reader gets the link's text as prose and no `@UUID` — the
+mirror of a link into a package that publishes documents and no pages.
+
+It is accepted only on a type whose **sole document is the JournalEntry its
+prose becomes** — `doc`, `place`, `lore` and `scenario`. On a type that
+compiles an Item, an Actor, a Macro, a Scene or an Adventure it is refused by
+name, because there it would drop the document the type exists to produce;
+the message names that document. It is read per system like any other
+`pack:`, so `<system>.pack: none` withholds one system's document while the
+shared declaration names a pack for the rest, and a configured pack may not
+be called `none`.
+
+Four declarations are refused, each with the reason:
+
+| written                                     | why it is refused                                                                            |
+| ------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| a **companion** pack                        | A companion is written by another pack's pass, so no note may be routed into one.            |
+| a pack **nothing answers to**               | The message lists the configured packs of that document type.                                |
+| a pack of **another document type**         | A note's `pack:` names a pack of its own document type.                                      |
+| **`none`** on a type with a second document | The Item, Actor, Macro, Scene or Adventure the type compiles into would be dropped, by name. |
 
 #### Template priority: which template wins
 

package/engine/field-reference.mjs

@@ -34,6 +34,9 @@
  * @module
  */
 
+import path from "node:path";
+import matter from "gray-matter";
+
 import { authoredFields, runtimeOnlyFields } from "./field-spec.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 
@@ -309,3 +312,135 @@ export function renderItemFieldReference({
     // and then reported stale by `--check` forever after.
     return lines.join("\n").replace(/\n+$/, "");
 }
+
+/**
+ * @param {unknown} value - Anything.
+ * @returns {boolean} Whether it is a mapping a field may be read out of.
+ */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Recursively merge `overlay` onto `base`. Plain objects merge key-by-key;
+ * everything else (arrays, primitives, `null`) replaces. Inputs are not
+ * mutated.
+ *
+ * @param {any} base - The generated envelope.
+ * @param {any} overlay - The consumer's declared `frontmatter`.
+ * @returns {any} The merged value.
+ */
+function deepMerge(base, overlay) {
+    if (overlay === undefined) return base;
+    if (!isPlainObject(base) || !isPlainObject(overlay)) return overlay;
+    const out = { ...base };
+    for (const [key, value] of Object.entries(overlay)) {
+        out[key] = key in base ? deepMerge(base[key], value) : value;
+    }
+    return out;
+}
+
+/**
+ * Whether a destination file sits under a content tree.
+ *
+ * The one question that decides whether `docs item-fields` writes a note
+ * envelope: `assets/content/` walks every file under it for its `type:`, so a
+ * generated page filed there needs one to publish at all, while a page filed
+ * anywhere else — a repository's own `docs/` — is read by nobody but Hugo's
+ * `--check` guard and the reader following a link, neither of which wants
+ * frontmatter.
+ *
+ * @param {string} destination - Absolute path of the file being written.
+ * @param {string} contentRoot - Absolute path of the content tree root
+ *   (`config.paths.content`).
+ * @returns {boolean} Whether `destination` resolves inside `contentRoot`.
+ */
+export function isUnderContentTree(destination, contentRoot) {
+    const relative = path.relative(contentRoot, destination);
+    return (
+        relative !== "" &&
+        relative !== ".." &&
+        !relative.startsWith(`..${path.sep}`) &&
+        !path.isAbsolute(relative)
+    );
+}
+
+/**
+ * A note's `shortcode`, derived from the basename of its destination file.
+ *
+ * Lowercase alphanumerics only — the address charset every other shortcode in
+ * the tree is held to — so `item-frontmatter.md` derives `itemfrontmatter`
+ * rather than carrying a hyphen no address segment permits.
+ *
+ * @param {string} destination - Where the note is written.
+ * @returns {string} The derived shortcode.
+ */
+export function shortcodeFromBasename(destination) {
+    return path
+        .basename(destination, path.extname(destination))
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, "");
+}
+
+/**
+ * The note envelope `docs item-fields` writes when its page lives in the
+ * content tree.
+ *
+ * The universal keys every note in the format carries: `type: doc`,
+ * `subType: reference` — this page is out-of-world lookup material, the same
+ * genre as every other generated reference — a `shortcode`, `name.full` from
+ * the page's title, and `pack: none`, since the page publishes to the website
+ * and compiles into no compendium document. A consumer's own
+ * `docs.itemFields.frontmatter` is deep-merged over it, so it may add keys or
+ * override any of the derived ones, `shortcode` included.
+ *
+ * @param {object} options
+ * @param {string} options.title - The page's H1, and `name.full`'s default.
+ * @param {string} options.shortcode - The derived shortcode, from
+ *   {@link shortcodeFromBasename}.
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {Record<string, unknown>} The envelope, ready for `matter.stringify`.
+ */
+export function itemFieldsEnvelope({ title, shortcode, frontmatter }) {
+    return deepMerge(
+        {
+            type: "doc",
+            subType: "reference",
+            shortcode,
+            name: { full: title },
+            pack: "none",
+        },
+        frontmatter,
+    );
+}
+
+/**
+ * Wrap the rendered item-fields page in the note envelope, when its
+ * destination is under the content tree.
+ *
+ * `--check` compares the **whole** file this returns, envelope included — a
+ * page committed with its old envelope by hand, or with none at all, is
+ * exactly the staleness the guard exists to catch.
+ *
+ * @param {string} body - The page {@link renderItemFieldReference} rendered.
+ * @param {object} options
+ * @param {string} options.title - The page's H1, threaded through to
+ *   `name.full`.
+ * @param {string} options.destination - Absolute path the page is written to.
+ * @param {string} options.contentRoot - Absolute path of the content tree
+ *   root (`config.paths.content`).
+ * @param {Record<string, unknown>} [options.frontmatter] - The consumer's
+ *   declared `docs.itemFields.frontmatter`.
+ * @returns {string} `body`, unchanged when `destination` is outside the
+ *   content tree; otherwise `body` with the note envelope stringified above it.
+ */
+export function renderItemFieldsPage(body, { title, destination, contentRoot, frontmatter }) {
+    if (!isUnderContentTree(destination, contentRoot)) return body;
+    const envelope = itemFieldsEnvelope({
+        title,
+        shortcode: shortcodeFromBasename(destination),
+        frontmatter,
+    });
+    return matter.stringify(body, envelope);
+}

package/engine/foundry-entries.mjs

@@ -70,6 +70,7 @@ import { resolveNoteId } from "./note-ids.mjs";
 import { compendiumUuid, currentType, packForType, pageUuid } from "./ids.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { isHomepage } from "./homepage.mjs";
+import { declaresNoPack } from "./pack-router.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
 import { assertNoDeclaredFolder } from "./folder-notes.mjs";
 import {
@@ -179,7 +180,17 @@ export function entriesForNote(fm, name, address, body, ctx) {
         // and its id is hashed under the `folder` namespace against its own
         // address rather than under `document`. Emitting one would publish an
         // `Item` UUID for a `Folder`, at an id no document carries.
-        id && !NEVER_PACKED_TYPES.has(String(type)) && !DERIVED_PACKED_TYPES.has(String(type)) ?
+        //
+        // And a note declaring **`pack: none`** is in no pack by its own
+        // statement: it publishes a page and compiles into nothing, so it has
+        // an address and no UUID. The shared declaration is what is read,
+        // because an entry names one document and this pass routes no system.
+        (
+            id &&
+            !NEVER_PACKED_TYPES.has(String(type)) &&
+            !DERIVED_PACKED_TYPES.has(String(type)) &&
+            !(routeFm && declaresNoPack(routeFm))
+        ) ?
             compendiumUuid(
                 foundryPackageId,
                 type,

package/engine/frontmatter-lint.mjs

@@ -1265,9 +1265,8 @@ export function lintNote(
             message: draftRetiredMessage(),
         });
     }
-    // Anchored at column 1 for the same reason `aliases` is: `section` names a
-    // configuration key too (`site.trees[].section`), and a nested one under
-    // some other block is not this field.
+    // Anchored at column 1 for the same reason `aliases` is: a nested
+    // `section` under some other block is not this field.
     if (Object.hasOwn(fm, "section")) {
         findings.push({
             file: note.file,

package/engine/helpers.mjs

@@ -38,7 +38,7 @@ import { foundryAddressProblem, pathnameProblem, resolvePathname } from "./pathn
 import log from "loglevel";
 
 import { loadPackConfig } from "./pack-config.mjs";
-import { packRouter } from "./pack-router.mjs";
+import { declaresNoPack, packRouter } from "./pack-router.mjs";
 import { contentPackage, foundryPackageId } from "./content-package.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
 import { PACKAGE_BASE } from "./content-address.mjs";
@@ -741,6 +741,9 @@ export function buildContentLinkIndex(
             // its prose compiles into lands — two documents, two packs.
             pack: router.resolveOrNull(fm, packForType(fm.type).docType),
             docPack: router.resolveOrNull(fm, "JournalEntry"),
+            // Whether the note declares `pack: none` and so has no document
+            // at all: a link to it names a page, never a compendium entry.
+            none: declaresNoPack(fm),
             shortcode: fm.shortcode ?? null,
             // What the note *is*, carried so a caller resolving a reference
             // can group by the family its target declares rather than only by

package/engine/ids.mjs

@@ -86,6 +86,18 @@ export const MAP_SUBTYPES = Object.freeze(["battlemap", "localmap", "regionalmap
  */
 export const JOURNAL_TYPES = Object.freeze(new Set(["doc", "place", "lore", "scenario"]));
 
+/**
+ * The `pack:` value that routes a note's document into no compendium.
+ *
+ * One reading, on the key that already decides which compendium receives a
+ * note: the note publishes to the site and compiles into nothing. Declared
+ * here, beside the pack table, so the configuration can refuse a pack of this
+ * name and the router can read the value from one spelling.
+ *
+ * @type {string}
+ */
+export const NO_PACK = "none";
+
 /**
  * Content type → the pack its documents compile into, and the document type
  * that pack holds.

package/engine/note-claims.mjs

@@ -91,6 +91,7 @@ import { JOURNAL_TYPES, MAP_TYPES, PACK_BY_TYPE, RETIRED_TYPES, currentType } fr
 import { itemTypes } from "./item-registry.mjs";
 import { docEntryTypes } from "./item-docs.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
+import { declaresNoPack } from "./pack-router.mjs";
 import { locateFrontmatterKey } from "./retired-fields.mjs";
 import { noteTypesFor, subtypeRow } from "./document-subtypes.mjs";
 import { KNOWN_DOCUMENT_SUBTYPE_MAPS } from "./subtype-registry.mjs";
@@ -641,6 +642,12 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
     // {@link claimedNoteTypes} states: its JSON is checked in, it has no pass,
     // and no note is routed into it.
     const configured = new Set((config.packs ?? []).filter((p) => !p.prebuilt).map((p) => p.type));
+    // Every system a pack declares, plus the shared position: a note that
+    // answers `pack: none` for all of them compiles into nothing anywhere.
+    const routed = [
+        undefined,
+        ...new Set((config.packs ?? []).map((p) => p.system).filter(Boolean)),
+    ];
 
     // The corpus this compile derived once, required rather than
     // derived here: this module is imported *by* the content index, so it
@@ -681,6 +688,20 @@ export function unclaimedNoteFindings(config = loadPackConfig(), sources, { reco
         // Every document it produces has somewhere to go.
         if (produces.length && !missing.length) continue;
 
+        // `pack: none`, on a type whose only document is the JournalEntry its
+        // prose becomes: the note compiles into nothing **by declaration**, so
+        // a missing JournalEntry pack drops nothing it meant to keep. A type
+        // that also produces an Item or an Actor is not excused here — the
+        // router refuses that declaration by name when a pass asks it, and
+        // where no pass does, the finding below still says nothing claims the
+        // note.
+        if (
+            produces.every((docType) => docType === "JournalEntry") &&
+            routed.every((system) => declaresNoPack(fm, system))
+        ) {
+            continue;
+        }
+
         // Some do and some do not: the note compiles, and one of its documents
         // is dropped in silence. A type nothing produces at all falls past this
         // to the unclaimed messages below, where `produces` being empty is itself

package/engine/pack-router.mjs

@@ -65,11 +65,22 @@
  *   a shared value that cannot describe a system-specific pack, so it does not
  *   answer and that system falls through to its own default. Both were silent
  *   losses of one system's whole document set.
+ * - **`pack: none` routes the document nowhere, on purpose.** The note is
+ *   walked, indexed, published and linkable, and no compendium receives it:
+ *   {@link createPackRouter}'s `resolve` answers `undefined`, which no pass's
+ *   name equals, so every pass passes over the note as one it does not own.
+ *   It is accepted only on a type whose sole document is the JournalEntry its
+ *   prose becomes — `doc` and the other journal-only types. On a type that
+ *   compiles an Item, an Actor, a Macro, a Scene or an Adventure it is refused
+ *   by name, because there the declaration would drop the document the type
+ *   exists to produce. Read per system like any other `pack:`, so a block may
+ *   say `none` for one system and the shared declaration may name a pack for
+ *   the rest.
  *
  * @module
  */
 
-import { packForType } from "./ids.mjs";
+import { NO_PACK, packForType } from "./ids.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { blockProperty, systemBlock } from "./system-block.mjs";
 
@@ -95,6 +106,35 @@ export class PackRoutingError extends Error {
  */
 export const PACK_FIELD = "pack";
 
+/**
+ * The `pack:` value that routes a note's document into no compendium — see
+ * {@link module:engine/ids.NO_PACK}. Re-exported here because this is the
+ * module that reads it; a configured pack may not take the name, so the value
+ * can never be mistaken for one.
+ */
+export { NO_PACK };
+
+/**
+ * Whether a note declares `pack: none` for one system's document.
+ *
+ * The same reading {@link createPackRouter}'s `resolve` applies: the system's
+ * block wins where it declares a pack, and the shared top-level value stands
+ * otherwise. Asked with no system, it reads the shared value alone, which is
+ * what every single-system build and the content index read.
+ *
+ * Pure, so the readers that never route — the Foundry-address pass, the link
+ * index, the unclaimed-type check — can ask it without a router.
+ *
+ * @param {object} fm - The note's frontmatter.
+ * @param {string} [system] - The system whose document is asked about.
+ * @returns {boolean} True when the answer for that document is `none`.
+ */
+export function declaresNoPack(fm, system) {
+    const declared =
+        system === undefined ? fm?.[PACK_FIELD] : blockProperty(fm, system, PACK_FIELD);
+    return declared === NO_PACK;
+}
+
 /**
  * Build the router for one configured pack list.
  *
@@ -103,7 +143,7 @@ export const PACK_FIELD = "pack";
  *
  * @param {readonly object[]} packs - The resolved `packs` list from
  *   `defineConfig`.
- * @returns {{resolve: (fm: object, docType: string, system?: string) => string,
+ * @returns {{resolve: (fm: object, docType: string, system?: string) => string|undefined,
  *   resolveOrNull: (fm: object, docType: string, system?: string) => string|undefined,
  *   packsOfType: (docType: string) => string[],
  *   defaultOf: (docType: string) => string|undefined}} The router.
@@ -179,6 +219,14 @@ export function createPackRouter(packs) {
     /** @param {object} fm */
     const noteLabel = (fm) => fm?.name?.full ?? fm?.shortcode ?? fm?.id ?? "a note";
 
+    /**
+     * `"a"` or `"an"`, so a document class reads as English in a message.
+     *
+     * @param {string} word - The word the article precedes.
+     * @returns {string} The article.
+     */
+    const article = (word) => (/^[AEIOUaeiou]/.test(word) ? "an" : "a");
+
     /**
      * The pack a note declaring none is routed to.
      *
@@ -212,8 +260,11 @@ export function createPackRouter(packs) {
      * @param {string} [system] - The system whose document is being routed. Its
      *   block's `pack:` wins over the shared one; without it only the shared
      *   declaration is read, which is every single-system build.
-     * @returns {string} The pack name.
-     * @throws {PackRoutingError} When the note routes nowhere.
+     * @returns {string|undefined} The pack name — or `undefined` where the
+     *   note declares `pack: none`, which no pass's name equals, so every pass
+     *   passes over the note as one it does not own.
+     * @throws {PackRoutingError} When the note routes nowhere, or declares
+     *   `pack: none` on a type that compiles a document beside its prose.
      */
     function resolve(fm, docType, system) {
         const inBlock = system === undefined ? undefined : systemBlock(fm, system)?.[PACK_FIELD];
@@ -225,6 +276,29 @@ export function createPackRouter(packs) {
         // JournalEntry — is not what the author was addressing.
         const ownDocType = packForType(fm?.type).docType;
 
+        // `none`: the note compiles into no document. Only a type whose own
+        // document *is* the JournalEntry may say so — for every other type
+        // the declaration would drop the Item, Actor, Macro, Scene or
+        // Adventure the type exists to produce, and its prose with it. The
+        // document class comes from the same table every pass routes by, so
+        // the refusal names what the compile would have written. Asked only
+        // by the pass that writes the note's own document, as every `pack:`
+        // is, so the refusal is reported once rather than once per pass.
+        if (declared === NO_PACK && docType === ownDocType) {
+            if (ownDocType !== "JournalEntry") {
+                const spelled = authoredInBlock ? `${system}.pack: ${NO_PACK}` : `pack: ${NO_PACK}`;
+                throw new PackRoutingError(
+                    `${noteLabel(fm)} declares \`${spelled}\`, but a ${fm?.type} note ` +
+                        `compiles into ${article(ownDocType)} ${ownDocType}, and ` +
+                        `\`pack: ${NO_PACK}\` would drop it. Only a type whose sole ` +
+                        `document is the JournalEntry its prose becomes may ` +
+                        `declare it — name the pack the ${ownDocType} goes to, or ` +
+                        `leave \`pack:\` unset for the default.`,
+                );
+            }
+            return undefined;
+        }
+
         // **A declaration naming another system's pack is not this system's
         // answer**, and which of two things that means depends on where
         // it was written.
@@ -328,7 +402,10 @@ export function createPackRouter(packs) {
          * @param {object} fm - The note's frontmatter.
          * @param {string} docType - The document type being addressed.
          * @param {string} [system] - The system whose document is addressed.
-         * @returns {string|undefined} The pack name, or `undefined`.
+         * @returns {string|undefined} The pack name, or `undefined` — for a
+         *   note that routes nowhere and for one declaring `pack: none`
+         *   alike. A caller that must tell the two apart asks
+         *   {@link declaresNoPack}.
          */
         resolveOrNull(fm, docType, system) {
             try {

package/engine/pdf-build.mjs

@@ -35,7 +35,7 @@
  * ## `publish.site` is the switch, and it is the only switch
  *
  * `homepage` mode fences the content surfaces off: the tree is not walked and
- * `sections`, `trees` and `landing` emit nothing however they are declared. A
+ * `sections` and `landing` emit nothing however they are declared. A
  * PDF of the content tree is a content surface by any reading — arguably the
  * most portable one there is — so it is fenced on exactly the same terms, by
  * asking the same {@link module:content-config.publishesContentPages} the
@@ -481,7 +481,7 @@ export async function buildPdf({ config, out, version = "", compile = true } = {
      * @returns {string} Typst markup.
      */
     const renderPage = (page, headingOffset, anchorPrefix) => {
-        const src = page.relPath ?? page.rel ?? page.base;
+        const src = page.relPath ?? page.base;
         const wikiErrors = [];
         const { markdown, errors } = expandContentTables(page.body, {
             docs: universe.get(page.pkg) ?? [],

package/engine/retired-fields.mjs

@@ -326,9 +326,8 @@ export function assertNoSectionField(fm, { file, absPath } = {}) {
     if (!fm || typeof fm !== "object" || !Object.hasOwn(fm, "section")) return;
 
     const err = new Error(`${sectionRetiredMessage(file)}.`);
-    // Anchored at column 1: `site.trees[].section` is a *configuration* key of
-    // the same name, and a nested `section:` inside some other block is not
-    // this field — a finding about the top-level one must not open on it.
+    // Anchored at column 1: a nested `section:` inside some other block is
+    // not this field — a finding about the top-level one must not open on it.
     const position = locateFrontmatterKey(absPath, "section", undefined, { topLevel: true });
     if (position) err.position = position;
     throw err;