@heroiclands/package-build 22.3.1 → 22.4.1

package/engine/content-links.mjs

@@ -621,21 +621,18 @@ export function buildLinkIndex(
 const SITE_HOST = /^(?:[a-z0-9-]+\.)*heroiclands\.org$/i;
 
 /**
- * Every package landing this build can name, as `package` → base.
+ * Every package front page this build can name, as `package` → base.
  *
- * **A landing needs no manifest, and that is what makes it work.** The link
- * manifest indexes content notes, and a homepage is deliberately not one — it
- * compiles to no document and is entered in no manifest. The reading that
- * follows from this, and that left a hardcoded URL as the only authored form,
- * is that a landing therefore cannot be addressed. It does not follow: a
- * landing's address is not a *note's* address but the **package's**, and
- * {@link PACKAGE_BASE} already records where each package is served. That is a
- * frozen constant compiled into every build, so consulting it walks no
- * tree, reads no manifest and builds no index — which is precisely why the
- * mechanism survives `homepage` mode, where the licensing fence means none of
- * those exist.
+ * **A front page needs no manifest, and that is what makes it work.** A
+ * homepage compiles to no document and is entered in no manifest, but its
+ * address is not a *note's* address but the **package's** — it is the mount's
+ * `_index.md`, published at `/<package>/` — and {@link PACKAGE_BASE} already
+ * records where each package is served. That is a frozen constant compiled
+ * into every build, so consulting it walks no tree, reads no manifest and
+ * builds no index — which is precisely why the mechanism survives `homepage`
+ * mode, where the licensing fence means none of those exist.
  *
- * The roster is consulted **for landings only**. Widening the package set the
+ * The roster is consulted **for front pages only**. Widening the package set the
  * other rules read would make them offer manifest-based advice about packages
  * no index has been fetched for.
  *
@@ -738,41 +735,30 @@ function readAddress(url, packages) {
  * not and cannot: it is published *verbatim* by every publishing mode, including
  * the homepage-only mode two fan-licensed packages ship under, where the content
  * tree is never walked and there is no index for a wikilink to resolve against.
- * So a landing addresses the web the way the web does — markdown links and
- * `url:` fields — and nothing was looking at those. SoHL's landing pointed at
- * `kb/creature/` and `kb/character/` from the day those types merged into
- * `being`: two 404s on the package's front page, through every build.
+ * So a homepage addresses the web the way the web does — markdown links in its
+ * body — and this is what looks at those. A dead link on the page a reader
+ * arrives at is the one nothing else would report.
  *
  * **What is checkable, stated plainly.** Only an address into this site is, and
  * only against facts this build already holds:
  *
  * - A **retired content type** in the path. The engine knows the retired names
- *   and what replaced it, so this is a fact rather than a guess — and it is
- *   exactly the SoHL defect.
+ *   and what replaced it, so this is a fact rather than a guess.
  * - A **hardcoded absolute URL** into this package's own prefix, or into one a
- *   a fetched index names. Every one of them has a better form to write, which
+ *   fetched index names. Every one of them has a better form to write, which
  *   is why every one is reported — including a bare `/<package>/`, which names
- *   another package's landing.
- *
- *   That last case was exempt until the better form was identified, on the
- *   reasoning that a landing is in no link manifest so nothing could resolve it.
- *   True, and beside the point: it does not need resolving. A landing's address
- *   *is* its package prefix, so `/<package>/` is the absolute URL with the host
- *   struck off — host-free, emitted verbatim, and needing no index, which is
- *   what lets it hold in homepage-only mode where the tree is never walked. The
- *   form was already accepted here; nothing had ever named it as the one to use.
- * - A **root-relative `url:`**, which the theme's `relURL` prefixes a second
- *   time. `href:` means "already resolved, use verbatim", so the same leading
- *   slash is correct there and is not reported.
+ *   another package's front page. A front page's address *is* its package
+ *   prefix, so `/<package>/` is the absolute URL with the host struck off —
+ *   host-free, emitted verbatim, and needing no index, which is what lets it
+ *   hold in homepage-only mode where the tree is never walked.
  * - A **wikilink**, which nothing on this page will ever resolve.
  *
  * **What is not checkable, and is not attempted.** Whether an external URL
  * answers — there is no network at build time, and a build must not fail because
  * a third party is down. And whether a live in-site address names a page that
- * exists: several of the surfaces a landing routes to are produced by other
- * tools entirely (generated API documentation, hand-authored Hugo sections), so
- * this build does not hold the set of published pages and would report a working
- * link as dead.
+ * exists: several of the surfaces a homepage routes to are produced by other
+ * tools entirely (generated API documentation, say), so this build does not
+ * hold the set of published pages and would report a working link as dead.
  *
  * @param {ReturnType<typeof buildLinkIndex>} index - The built index.
  * @returns {Array<{note: object, field: string, url: string, text: string,
@@ -814,7 +800,7 @@ export function auditHomepageLinks(index) {
             );
         }
 
-        for (const { field, url, kind } of homepageAddresses(note.fm, note.body)) {
+        for (const { field, url } of homepageAddresses(note.body)) {
             // Counted for every address, checked or not, so the count is
             // the literal's nth appearance in the file rather than the nth
             // *finding* about it — two rules can fire on one address.
@@ -853,34 +839,13 @@ export function auditHomepageLinks(index) {
                     prefix === index.contentPackage ?
                         `hardcoded absolute URL into this package's own ` +
                             `address — write the package-relative ` +
-                            `"${rest}/", which the landing resolves ` +
-                            `against the site so the page follows the mount`
+                            `"${rest}/", which a browser resolves against ` +
+                            `the homepage's own address, the package root`
                     :   `hardcoded absolute URL into package "${prefix}" ` +
                             `— resolve it through that package's link ` +
                             `manifest, whose entries carry the address, so a ` +
                             `relocation does not leave this page behind`,
                 );
-            } else if (shape === "rooted" && kind === "url") {
-                const rest = prefix ? segments.slice(1).join("/") : segments.join("/");
-                report(
-                    field,
-                    url,
-                    url,
-                    occurrence,
-                    // A `url:` is package-relative by construction, so it
-                    // cannot address anything outside this package at all —
-                    // there is no relative spelling of another package's root.
-                    // `href:` is the field for an address already resolved.
-                    !rest ?
-                        `url "${url}" addresses ` +
-                            (prefix ? `package "${prefix}"'s landing` : `the site root`) +
-                            `, but a landing's url: is package-relative and ` +
-                            `cannot leave this package — write ` +
-                            `href: "${url}", which is used verbatim`
-                    :   `url "${url}" is root-relative, but a landing's url: ` +
-                            `is resolved against the site — write "${rest}/", ` +
-                            `or href: for an address that is already resolved`,
-                );
             }
 
             // The retired-type rule reads the path *inside* the package, so an

package/engine/diagnostics.mjs

@@ -297,7 +297,7 @@ export function positionOfLiteral(text, needle, occurrence = 1) {
  *
  * **`key: true` addresses the declaration rather than the value.** A finding
  * about a *value* — this pack name is not in `packs[]` — belongs on the value,
- * which is the default. A finding that names a **field** — `\`site.sections.x\`
+ * which is the default. A finding that names a **field** — `\`site.notfound.x\`
  * is not a recognized option` — sends the reader to look for that field, so the
  * position should be the field's own, and in a flow mapping
  * (`{ title: X, banner: Y }`) the two are different columns on one line. The
@@ -347,7 +347,7 @@ export function positionOfYamlPath(text, keyPath, { key = false } = {}) {
  * The YAML key path a **dotted field path** addresses.
  *
  * Configuration checks report the offending key as the path a reader would
- * write it — `packs[1].name`, `site.sections.affliction.title` — because that
+ * write it — `packs[1].name`, `site.notfound.links[0].url` — because that
  * is what the message has to say. {@link positionOfYamlPath} addresses a node
  * by segments instead, so this is the one translation between them: `.`
  * separates map keys, and a bracketed suffix is a sequence index.

package/engine/field-reference.mjs

@@ -442,5 +442,11 @@ export function renderItemFieldsPage(body, { title, destination, contentRoot, fr
         shortcode: shortcodeFromBasename(destination),
         frontmatter,
     });
-    return matter.stringify(body, envelope);
+    const page = matter.stringify(body, envelope);
+    // `matter.stringify` closes the frontmatter fence directly onto the
+    // body's first line; Prettier's markdown printer requires a blank line
+    // between them, so a page written without one fails a consumer's
+    // `lint:format` the moment it is committed. Insert it here rather than
+    // let the generator and the formatter rewrite the file back and forth.
+    return page.replace(/^(---\n[\s\S]*?\n---\n)/, "$1\n");
 }

package/engine/homepage.mjs

@@ -20,24 +20,19 @@
  * written by a person: what the module is, which system it needs, how to install
  * it, where its source lives. Nothing about it is derived.
  *
- * **Authored, not assembled.** An earlier sketch generated the page in tiers —
- * identity and licence from the manifest, install URL from the release address,
- * "requires" links from `relationships`, a card per configured section. It would
- * have worked and needed almost no authoring, and it produces a page nobody
- * chose the contents of. The things that matter most on these pages cannot be
- * derived: that Kethira requires buying the book from Keléstia, what Thalorna's
- * setting *is*, which of twenty sections a reader should start with. So the only
- * thing defaulted here is the title, from `packageBuild.manifest.title`, so that
- * the package's name is not written twice.
+ * **Authored, not assembled.** The things that matter most on a front page
+ * cannot be derived: that Kethira requires buying the book from Keléstia, what
+ * Thalorna's setting *is*, which of twenty pages a reader should start with. So
+ * the only thing defaulted here is the title, from `packageBuild.manifest.title`,
+ * so that the package's name is not written twice. Everything else is the body,
+ * which is why a `landing:` card block is refused: the homepage is a page with a
+ * body, rendered as one, and an index of what the package publishes is a `doc`
+ * note carrying a content table.
  *
  * **Dispatched by `type`, not by filename.** A fixed `homepage.md` the walker
  * special-cased would be the anomaly: notes are routed by frontmatter, not by
  * location, and `NOTE_SCHEMAS` already routes `doc`, `macro`, `being` and the
- * map types. `homepage` is one more entry whose compile step emits a page. It is
- * deliberately not `README.md`: `landing: readme` already means "a `README.md`
- * is its section's landing page", and `sohl-thalorna/assets/content/README.md`
- * is a developer explainer about the source tree — adopting that name would make
- * Thalorna's public front page its build documentation.
+ * map types. `homepage` is one more entry whose compile step emits a page.
  *
  * **Engine, not `sohl/`.** The `engine/` ÷ `sohl/` line separates *note-format*
  * knowledge from *game-system* knowledge, and a homepage is note format: it
@@ -47,27 +42,24 @@
  * type living in the SoHL registry would be unavailable to HM3 and to every HM3
  * module, which is most of the packages that need a homepage and nothing else.
  *
- * **Addressed like every other note.** A homepage declares a `shortcode` —
- * conventionally {@link HOMEPAGE_SHORTCODE} — and publishes at its address,
- * `/<package>/<type>-<shortcode>/`, written by the same rule as everything else.
- * It used to publish at `/<package>/` from a fixed destination, and
- * that is why it refused `name` and `shortcode`: a URL derived from `name.full`
- * while the destination did not, so `[[homepage-<shortcode>]]` resolved *green*
- * to a page nothing wrote. A page's URL is its address now, so the
- * computed address is the published one and there is nothing left to refuse.
- * The package's own `/<package>/` becomes a redirect its repository authors —
- * see `CONTENT.md` — rather than a page this build writes.
- *
- * `id` is still refused, on ground the change does not touch: a homepage
- * compiles into no document, so it carries no compendium UUID and appears in no
- * pack and in no link-manifest entry.
+ * **Published at the package root, addressed like every other note.** A
+ * homepage is written as the mount's `_index.md`, so Hugo's `home` kind renders
+ * it at `/<package>/` — the address a reader expects a package's front page at,
+ * and the one `package.json`'s `homepage` states. It still declares a
+ * `shortcode` — conventionally {@link HOMEPAGE_SHORTCODE} — because that is what
+ * a link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and
+ * it resolves to `/<package>/`. The shortcode names the page in links; the
+ * address is the package root.
+ *
+ * `id` is refused, on its own ground: a homepage compiles into no document, so
+ * it carries no compendium UUID and appears in no pack and in no link-manifest
+ * entry.
  *
  * @module
  */
 
 import fs from "node:fs";
 
-import { addressSlug } from "./content-address.mjs";
 import { matchAllOutsideCode } from "./code-fences.mjs";
 import { formatLocator, positionInFrontmatter } from "./diagnostics.mjs";
 
@@ -107,20 +99,15 @@ export const HOMEPAGE_SHORTCODE = "root";
 /**
  * The file a homepage is written to, relative to the package's site root.
  *
- * Its **address**, flat at the package root, and stated in the page's own `url`
- * — the same separation every other page has, where the directory
- * decides the Hugo section and the front matter decides the URL. Flat rather
- * than inside a `homepage/` section directory, because a homepage is not one of
- * a kind: a section holding exactly one page would publish a landing at
- * `/<package>/kb/homepage/` that nothing links to and nobody wrote.
+ * The mount's own `_index.md`: Hugo renders it as the `home` kind, at
+ * `baseURL` — which is `/<package>/`, the package's own address. One fixed
+ * destination rather than one derived from the note's address, because the
+ * homepage's address *is* the package root; the note's `shortcode` names the
+ * page in links and decides no file.
  *
- * @param {object} fm - Parsed frontmatter.
- * @returns {string} The destination filename, e.g. `homepage-root.md`.
- * @throws {Error} When the note declares no shortcode, and so has no address.
+ * @type {string}
  */
-export function homepageDestination(fm) {
-    return `${addressSlug(fm)}.md`;
-}
+export const HOMEPAGE_DESTINATION = "_index.md";
 
 /**
  * Whether a note's frontmatter declares the homepage type.
@@ -133,17 +120,16 @@ export function isHomepage(fm) {
 }
 
 /**
- * The top-level field a homepage refuses, and what it would decide.
+ * The top-level fields a homepage refuses, and what each would decide.
  *
- * **One field rather than three.** `name` and `shortcode` are
- * refused because a page's URL derived from `name.full` while a homepage's
- * destination was fixed, so the address a `shortcode` computed named a page the
- * site build never wrote. A page's URL is its address now and a homepage
- * publishes at its own, so both fields decide exactly what they decide
- * everywhere else and are permitted.
+ * `id` is the Foundry document id a compendium UUID is built from, and a
+ * homepage compiles into no document. `landing` is a card block; the homepage
+ * is a page with a body, rendered as one, so nothing reads it — and an index
+ * of what the package publishes is a `doc` note carrying a content table,
+ * authored where every other page is.
  *
- * `id` is untouched by that, and stays: it is the Foundry document id a
- * compendium UUID is built from, and a homepage compiles into no document.
+ * `name` and `shortcode` are permitted: the shortcode is what a link is
+ * written with, and `name` titles the page like every other note's.
  *
  * **A named class, not an allow-list, and that boundary is the decision.** A
  * homepage's frontmatter is *emitted into the published page*
@@ -167,6 +153,14 @@ export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
                 "homepage compiles into no document — it appears in no pack " +
                 "and in no link manifest. Delete it",
         ],
+        [
+            "landing",
+            "`landing` decides nothing on a `type: homepage` note: the homepage " +
+                "is a page with a body, rendered as one, and no card block is " +
+                "read off it. Write the page's links in its body, and author an " +
+                "index of what the package publishes as a `doc` note carrying a " +
+                "content table. Delete it",
+        ],
     ]),
 );
 
@@ -174,7 +168,7 @@ export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
  * What the address rule says about one note's top-level fields.
  *
  * Two statements about the same thing, so they are made together: the field a
- * homepage **owes** and the field it may **not** write.
+ * homepage **owes** and the fields it may **not** write.
  *
  * The missing `shortcode` comes first, and is located at `type:` rather than at
  * a key that is not there — the `homepage` value is what makes the field
@@ -184,8 +178,9 @@ export const HOMEPAGE_REFUSED_FIELDS = Object.freeze(
  * diagnostic per finding walks down the file.
  *
  * Presence is the whole test for a refused field, and absence-or-blank for the
- * required one: `shortcode:` authored empty is no address, and a value cannot
- * make `id` mean something on a page that compiles to no document.
+ * required one: `shortcode:` authored empty is no address, and no value can
+ * make `id` or `landing` mean something on a page that compiles to no document
+ * and renders as its body.
  *
  * Each finding carries the `locator` key to position it at, because the two
  * things that would resolve one — the raw note text and the position helper —
@@ -220,10 +215,10 @@ export function checkHomepageAddressFields(fm, { isAuthored } = {}) {
             locator: { key: "type", literal: HOMEPAGE_TYPE },
             message:
                 "a `type: homepage` note declares a `shortcode`, like every " +
-                "other note: it is addressed as `homepage-<shortcode>` and " +
-                "published at `/<package>/homepage-<shortcode>/`, which is " +
-                "where `[[homepage-<shortcode>|Text]]` lands. Write " +
-                `\`shortcode: ${HOMEPAGE_SHORTCODE}\` — the package landing is ` +
+                "other note: it is addressed as `homepage-<shortcode>`, which " +
+                "is what `[[homepage-<shortcode>|Text]]` is written with to " +
+                "reach the package's front page at `/<package>/`. Write " +
+                `\`shortcode: ${HOMEPAGE_SHORTCODE}\` — the front page is ` +
                 `\`homepage-${HOMEPAGE_SHORTCODE}\` in every package`,
         });
     }
@@ -247,13 +242,11 @@ export function checkHomepageAddressFields(fm, { isAuthored } = {}) {
  *   this exists to prevent, and it is silent — the site build reports `wrote 0
  *   homepage(s)` and exits 0.
  * - _Two_ and it serves a page nobody chose. **This is a cardinality rule, and
- *   only that.** A homepage is written at its own address, so two of them
- *   publish two pages and collide over nothing; the
- *   duplicate-address check catches only the pair that happen to share a
- *   shortcode, and says nothing at all about a `homepage-root` beside a
- *   `homepage-front`. Which of the two the redirect at `/<package>/` should
- *   name is a question nothing here can answer, and both being reachable is
- *   not an answer to it.
+ *   only that.** Both are written to the mount's `_index.md`, so the second
+ *   silently overwrites the first; the duplicate-address check catches only
+ *   the pair that happen to share a shortcode, and says nothing at all about
+ *   a `homepage-root` beside a `homepage-front`. Which of the two should be
+ *   the front page is a question nothing here can answer.
  *
  * Neither has a safe default, so neither is a warning. A warning is the right
  * severity for something a build can proceed past correctly, and a build that
@@ -315,10 +308,9 @@ export function checkHomepageCount(found, { contentBase, contentPackage }) {
             message:
                 `duplicate \`type: homepage\` note, also declared by ` +
                 `${others.join(", ")}; a package has one front page` +
-                `${contentPackage ? `, at${address}` : ""}, and each of these ` +
-                `publishes at an address of its own — so nothing here can say ` +
-                `which one that address should redirect to. Keep one, and make ` +
-                `the rest ordinary notes`,
+                `${contentPackage ? `, at${address}` : ""}, and nothing here ` +
+                `can say which of these it should be. Keep one, and make the ` +
+                `rest ordinary notes`,
         };
     });
 }
@@ -371,24 +363,15 @@ export function homepageTitle(fm, config) {
 /**
  * The frontmatter a homepage publishes with.
  *
- * The note's own, plus the derived values every emitted page carries: the
- * resolved `title`, the package the build derived — no note declares one
+ * The note's own, plus the two derived values every emitted page carries: the
+ * resolved `title`, and the package the build derived — no note declares one
  * (`package:` is retired) and the theme's breadcrumb partial reads
- * `.Params.package` — and its **address**.
- *
- * The address is stated as `url` for the same reason every other page states
- * one: Hugo publishes a page where its file sits unless told otherwise,
- * and a homepage's file sits at the package's site root. `slug` is written
- * beside it because it is the last segment of that address and Hugo's own key
- * for one; it decides nothing while `url` is present, but a page carrying only
- * `url` would report a slug Hugo had inferred from the filename.
- *
- * **Site-root relative, and so carrying no package base**, exactly as
- * `pageFrontmatter` states a content page's: Hugo resolves a `url`
- * against `baseURL`, whose path is already where the package is served, so a
- * stated base was written twice and published the landing at
- * `/<package>/<package>/homepage-root/`. Where the package is served is what
- * every *href* is composed from and it reaches this page's address not at all.
+ * `.Params.package`.
+ *
+ * **No `url` and no `slug`.** Hugo publishes the `home` kind at `baseURL`,
+ * whose path is already where the package is served, so the page has no
+ * address to state; a content page states one because its file sits under the
+ * mount and its address does not.
  *
  * An authored `aliases` is dropped for the same reason it is on every other
  * page: Hugo reads it as URL redirects, so passing it through would publish a
@@ -400,11 +383,9 @@ export function homepageTitle(fm, config) {
  * @param {string} options.contentPackage - The package this build publishes.
  * @param {string} options.title - The resolved title.
  * @returns {object} The frontmatter to write.
- * @throws {Error} When the note declares no shortcode, and so has no address.
  */
 export function homepageFrontmatter(fm, { contentPackage, title }) {
-    const slug = addressSlug(fm);
-    const data = { ...fm, package: contentPackage, title, slug, url: `/${slug}/` };
+    const data = { ...fm, package: contentPackage, title };
     delete data.aliases;
     return data;
 }
@@ -412,103 +393,41 @@ export function homepageFrontmatter(fm, { contentPackage, title }) {
 /**
  * An inline markdown link — `[text](target)`, but not an image.
  *
- * Reference-style links are deliberately not matched: a landing's prose fields
- * are single YAML scalars with nowhere to put a link definition, so a `[x][y]`
- * in one could never resolve and is not an address anybody wrote.
+ * Reference-style links are deliberately not matched: a homepage is published
+ * verbatim, so a `[x][y]` whose definition sits in the body reaches the reader
+ * as Hugo renders it, and one whose definition is missing is a defect the
+ * rendered page shows for itself.
  *
  * @type {RegExp}
  */
 const MARKDOWN_LINK = /(?<!!)\[[^\]]*\]\(\s*([^)\s]+)(?:\s+"[^"]*")?\s*\)/g;
 
 /**
- * The two frontmatter keys that hold an address, and what each one means.
- *
- * They are **not** interchangeable, and a check that treated them as one would
- * be wrong about both. The theme resolves a `url` against the site with
- * `relURL`, so a package writes `kb/rules/` and is served `/sohl/kb/rules/`
- * without ever naming its own prefix. An `href` is an address that is *already*
- * resolved and is used verbatim — which is what `cards.source: sections` fills
- * in, since a section's permalink already carries the prefix.
- *
- * So a leading `/` is a defect in a `url` (it is prefixed a second time) and
- * correct in an `href`.
- *
- * @type {ReadonlySet<string>}
- */
-export const HOMEPAGE_ADDRESS_KEYS = Object.freeze(new Set(["url", "href"]));
-
-/**
- * Collect the markdown links in one prose value.
+ * Every address a homepage carries: the markdown links in its body.
  *
- * @param {string} text - The value.
- * @param {string} field - Where it came from.
- * @param {string} kind - The address kind to record.
- * @param {object[]} out - Accumulator.
- * @param {boolean} [skipCode] - Whether to ignore links inside code.
- */
-function collectProse(text, field, kind, out, skipCode = false) {
-    const pattern = new RegExp(MARKDOWN_LINK.source, "g");
-    const matches = skipCode ? matchAllOutsideCode(text, pattern) : [...text.matchAll(pattern)];
-    for (const m of matches) out.push({ field, url: m[1], kind });
-}
-
-/**
- * Every address a homepage carries, wherever it is written.
- *
- * **Both halves of the page are in scope, and that is the finding rather than
- * the assumption.** Of the six homepages authored today, four carry every link
- * in the body as ordinary markdown and two carry them in `landing:` — and the
- * one whose dead links prompted the check has an *empty body*, so a body-only
- * reading would have found nothing at all on it. A dead link in a card is
- * exactly as broken as one in a paragraph.
+ * Nowhere else: the frontmatter holds no address, because a homepage is a
+ * page with a body and the card block that once carried links is refused.
+ * Top-level `title` and `description` are not walked — they are set as text,
+ * never rendered as markdown — and `banner:` is not an address: it is an image
+ * path resolved through the CDN base, and `banner: none` is a sentinel rather
+ * than a target.
  *
- * Three shapes are gathered, and the caller needs to tell them apart because
- * the rules differ:
+ * A body link is emitted as written and resolved by the browser against the
+ * homepage's own address, which *is* the package root, so a package-relative
+ * one (`kb/rules/`) lands where a reader expects.
  *
- * - **`url`** — package-relative, resolved against the site by the theme.
- * - **`href`** — already resolved, used verbatim.
- * - **prose and body markdown links** — emitted as written and resolved by the
- *   browser against the landing's own address, which *is* the package root, so
- *   a relative one means the same thing a `url` does.
+ * Links inside code are ignored, so an example in a fenced block is not
+ * reported as a dead address.
  *
- * `banner:` is not an address: it is an image path resolved through the CDN
- * base, and `banner: none` is a sentinel rather than a target. Top-level
- * `title` and `description` are not walked either — they are set as text, never
- * rendered as markdown.
- *
- * @param {object|null|undefined} fm - The note's frontmatter.
  * @param {string} [body] - The note's markdown body.
  * @returns {Array<{field: string, url: string, kind: string}>} Every address,
- *   frontmatter first and then the body, each with the dotted path it was
- *   written at.
+ *   in body order, each recorded at `field: "body"` with `kind: "body"`.
  */
-export function homepageAddresses(fm, body = "") {
+export function homepageAddresses(body = "") {
     const out = [];
-
-    const walk = (value, field) => {
-        if (typeof value === "string") {
-            collectProse(value, field, "prose", out);
-            return;
-        }
-        if (Array.isArray(value)) {
-            value.forEach((v, i) => walk(v, `${field}[${i}]`));
-            return;
-        }
-        if (!value || typeof value !== "object") return;
-        for (const [key, v] of Object.entries(value)) {
-            const child = `${field}.${key}`;
-            // An address field holds an address, not prose: reading it for
-            // markdown links as well would report the same target twice
-            // whenever one happened to look like a link.
-            if (HOMEPAGE_ADDRESS_KEYS.has(key) && typeof v === "string") {
-                out.push({ field: child, url: v, kind: key });
-                continue;
-            }
-            walk(v, child);
-        }
-    };
-
-    walk(fm?.landing, "landing");
-    collectProse(String(body ?? ""), "body", "body", out, true);
+    const pattern = new RegExp(MARKDOWN_LINK.source, "g");
+    for (const m of matchAllOutsideCode(String(body ?? ""), pattern)) {
+        out.push({ field: "body", url: m[1], kind: "body" });
+    }
     return out;
 }

package/engine/metadata-index.mjs

@@ -50,6 +50,7 @@ import { packageBuildRecords } from "./packagebuild-index.mjs";
 
 export { metadataFileName };
 import { PACKAGE_BASE, readCanonicalKey, resolvePackageUrl } from "./content-address.mjs";
+import { HOMEPAGE_TYPE } from "./homepage.mjs";
 
 /**
  * Written once a fetch completes, so a half-finished cache is never used.
@@ -365,9 +366,12 @@ export function loadForeignIndexes(config, localPackages, bases = PACKAGE_BASE)
                 // must tolerate that rather than invent an href, exactly as it
                 // already tolerates an entry with no `uuid`.
                 url:
-                    web && record.address.slug ?
-                        resolvePackageUrl(`${record.address.slug}/`, base)
-                    :   undefined,
+                    !web || !record.address.slug ? undefined
+                        // A package's homepage is its root: the note is the
+                        // mount's `_index.md`, so `[[thalorna-homepage-root]]`
+                        // lands on `/thalorna/`, not on a page below it.
+                    : parts.type === HOMEPAGE_TYPE ? base
+                    : resolvePackageUrl(`${record.address.slug}/`, base),
                 uuid: foundry?.uuid,
                 doc: record.documentation ?? undefined,
                 anchors: foundry?.anchors,

package/engine/note-vocabulary.mjs

@@ -496,26 +496,6 @@ export function hasTag(fm, tag) {
     return false;
 }
 
-/**
- * Whether a note carries any `tags:` at all, however authored.
- *
- * The one question the site build asks of tags in aggregate — whether the
- * tree publishes taxonomy pages — rather than about a particular tag. Reads
- * `tags` and `tag` exactly as {@link hasTag} does, and treats an empty list
- * or a blank string as carrying none.
- *
- * @param {object|null|undefined} fm - Parsed frontmatter.
- * @returns {boolean} Whether the note carries at least one tag.
- */
-export function hasAnyTag(fm) {
-    const raw = fm?.tags ?? fm?.tag;
-    if (raw == null) return false;
-    for (const entry of Array.isArray(raw) ? raw : [raw]) {
-        if (typeof entry === "string" && entry.trim() !== "") return true;
-    }
-    return false;
-}
-
 /**
  * Whether a note is tagged as an unfinished **draft**.
  *

package/engine/pdf-build.mjs

@@ -34,8 +34,8 @@
  *
  * ## `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` and `landing` emit nothing however they are declared. A
+ * `homepage` mode fences the content surfaces off: the tree is not walked for
+ * pages, whatever else the configuration declares. 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