@heroiclands/package-build 23.13.0 → 24.0.1

package/docs/configuration.md

@@ -160,8 +160,8 @@ which applies before either loader form gets a chance to derive anything.
 
 #### `homepage`
 
-The address a package's site is served at — read by the generated Hugo
-configuration for `baseURL`, independently of the Foundry manifest's own
+The address a package's site is served at — read by the site build for the
+site's base URL, independently of the Foundry manifest's own
 `url`, which derives from `contentPackage` instead (see
 [`packageBuild.manifest`](#packagebuildmanifest)). `null` when the package
 declares none.
@@ -179,14 +179,18 @@ declares none.
 `homepage` is not itself checked against `contentPackage` by `defineConfig`.
 `checkHomepage` in `config.mjs` is the check: `homepage` is required
 unconditionally — every package publishes a site — and must be an absolute
-URL whose path ends `/<contentPackage>/`. `package-build site` makes it
-before the generated `baseURL` is written, so a missing or mismatched
+URL whose path ends `/<contentPackage>/` — or, for a site that states
+[`site.base`](#site), whose path is that base, so a site served at `/` has
+the root of its origin as its `homepage`. `package-build site build` makes
+it before the site's settings are composed, so a missing or mismatched
 `homepage` is a finding on every site build:
 
 > ``package-build config: `homepage` is not declared in `package.json`, and every package needs one to build its site's `baseURL` from. Add `https://www.heroiclands.org/<contentPackage>/`.``
 
 > ``package-build config: `homepage` is `https://www.heroiclands.org/harn-ensemble`, but `contentPackage` is `harnensemble` — a package's site is served at `https://www.heroiclands.org/harnensemble/`, so `package.json`'s `homepage` must end `/harnensemble/`.``
 
+> ``package-build config: `homepage` is `https://www.heroiclands.org/heroiclands/`, but `site.base` is `/`, so `package.json`'s `homepage` must be the root of its origin.``
+
 #### `author`
 
 The package's byline: the first entry of [`authors`](#authors), in npm's
@@ -604,7 +608,7 @@ HeroicLands layout, resolved against `rootDir`:
 | `paths.unpack`          | `build/tmp/packs`        | Where `unpack` extracts JSON back to.                                                                                              |
 | `paths.foreignCache`    | `build/cache/foreign`    | Where a dependency declaring `itemCatalog: true` or `assetArchive: true` is unpacked.                                              |
 | `paths.metadataCache`   | `build/cache/metadata`   | Where a published content index is fetched to, for every declared dependency and every relationship declaring `itemCatalog: true`. |
-| `paths.navigationCache` | `build/cache/navigation` | Where the site navigation heroiclands.org publishes is fetched to, for the generated Hugo menu.                                    |
+| `paths.navigationCache` | `build/cache/navigation` | Where the site navigation heroiclands.org publishes is fetched to, for the site's menu.                                            |
 
 Every configured path must be **relative** — an absolute one would escape
 the repository the config anchors:
@@ -949,25 +953,29 @@ Any other key under `docs.itemFields` is refused:
 
 **Type:** object · **Optional** · every key defaults to nothing published:
 
-| Key                | Type     | Default                                      |
-| ------------------ | -------- | -------------------------------------------- |
-| `site.base`        | string   | `""`                                         |
-| `site.title`       | string   | `""`, required when no manifest title exists |
-| `site.assets`      | string   | `""`, but required for `package-build site`  |
-| `site.description` | string   | `""`, but required for `package-build site`  |
-| `site.packages`    | string[] | `[]`                                         |
-| `site.pass`        | string   | `""`                                         |
-| `site.passOptions` | object   | `{}`                                         |
-| `site.notfound`    | object   | `null`                                       |
-| `site.hugo`        | object   | `{}`                                         |
-| `site.search`      | boolean  | `true`                                       |
-| `site.maps`        | boolean  | `true`                                       |
+| Key                 | Type     | Default                                      |
+| ------------------- | -------- | -------------------------------------------- |
+| `site.base`         | string   | `""`                                         |
+| `site.title`        | string   | `""`, required when no manifest title exists |
+| `site.assets`       | string   | `""`, but required for `site build`          |
+| `site.description`  | string   | `""`, but required for `site build`          |
+| `site.packages`     | string[] | `[]`                                         |
+| `site.pass`         | string   | `""`                                         |
+| `site.passOptions`  | object   | `{}`                                         |
+| `site.notfound`     | object   | `null`                                       |
+| `site.search`       | boolean  | `true`                                       |
+| `site.maps`         | boolean  | `true`                                       |
+| `site.sections`     | object   | `{}`                                         |
+| `site.feed`         | string   | `""`                                         |
+| `site.tags`         | boolean  | `false`                                      |
+| `site.sitemaps`     | string[] | `[]`, and only at the root of an origin      |
+| `site.mergeIndexes` | string[] | `[]`                                         |
 
 The authored content tree determines which pages reach the web. `site` is
 framing: 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.
+[site settings](#what-the-site-build-reads) that is genuinely this
+repository's own.
 
 **A site is its homepage and its pages.** The `type: homepage` note is the
 package's front page at `/<contentPackage>/`, and every other note is one page
@@ -981,15 +989,13 @@ So a page of documentation is a note — `type: doc`, addressed by its
 shortcode, and `pack: none` where it compiles into no Foundry document — and
 there is no second mechanism for mounting a directory of markdown.
 
-Where the Hugo tree is written is not a choice. `package-build site` writes
-the whole Hugo source tree under `build/hugo/` — the generated `hugo.toml`,
-the content mount at `build/hugo/content/`, Hugo's own cache — as a sibling
-of the deployment root `build/site/`, so nothing Hugo reads lands in what is
-published.
+Where the site is written is not a choice. `package-build site build`
+renders it under the deployment root `build/site/`, at
+`build/site/<contentPackage>/` (or under the path `site.base` states).
 
 > ``package-build config: `site` must be a mapping.``
 
-> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, title, assets, description, packages, pass, passOptions, notfound, hugo, search, maps).``
+> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, title, assets, description, packages, pass, passOptions, notfound, search, maps, sections, feed, tags, sitemaps, mergeIndexes).``
 
 `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
@@ -1002,8 +1008,8 @@ Absolute, and the trailing slash is trimmed:
 
 > ``package-build config: `site.assets` must be an absolute `http://` or `https://` address — it is the host every package's imagery is served from, and a relative value resolves against whichever page happens to carry the image.``
 
-`package-build site` refuses to generate a configuration with no
-`site.assets` at all — there is no defensible default, because the theme
+`package-build site build` refuses a configuration with no `site.assets` at
+all — there is no defensible default, because the theme
 resolves every relative asset against it:
 
 > ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
@@ -1014,7 +1020,7 @@ host, at `<site.assets>/<contentPackage>/icons/<basename>` and
 bucket behind the CDN is served at `site.assets`, so an object's key is its
 path below this value.
 
-The generated Hugo configuration carries the same host as
+The site settings carry the same host as
 `params.cdnBaseURL`, which the theme resolves a relative asset path against.
 The two are one value read by two readers: the toolchain emits it into a
 page, and the theme joins it onto anything the toolchain left relative.
@@ -1026,7 +1032,7 @@ absent.
 `site.description` is the site's `<meta name="description">` — one plain
 sentence, distinct from the Foundry package browser's pitch
 ([`packageBuild.manifest.descriptionHtml`](#packagebuildmanifest), which
-allows HTML). Required for `package-build site`, the way its title is:
+allows HTML). Required for `package-build site build`, the way its title is:
 
 > ``package-build config: `site.description` is not declared, and the site's `<meta name="description">` reads from it.``
 
@@ -1047,8 +1053,8 @@ names a registry):
 `site.passOptions` has no further shape of its own — it is passed to the
 resolved `site.pass` bundle unchanged.
 
-`site.notfound` is the wording of the "page not found" page, written into
-the generated Hugo configuration as `params.notfound`. The theme renders
+`site.notfound` is the wording of the "page not found" page, carried in the
+site settings as `params.notfound`. The theme renders
 the page for every site; what a repository supplies is the tagline, the
 noun the body prose calls the site, and the routes back. `tagline` and
 `sitenoun` are required once the block is present — a block declaring only
@@ -1089,31 +1095,8 @@ site:
 
 > ``package-build config: `site.notfound.links[<index>].<key>` is not a recognized option (expected one of: title, url, text).``
 
-`site.hugo` is a mapping deep-merged over the generated Hugo configuration,
-last — the escape hatch for the one key nobody anticipated. A repository
-whose homepage reproduces a notice whose bare URLs must stand unedited turns
-Goldmark's autolinker off:
-
-```yaml
-site:
-  hugo:
-    markup:
-      goldmark:
-        extensions:
-          linkify: false
-```
-
-Objects merge; an array or a scalar replaces what the generator wrote. Every
-key the generator writes is refused here, naming its source — see
-[the generated Hugo configuration](#the-generated-hugo-configuration) — so
-the block cannot grow into a second configuration file:
-
-> ``package-build config: `site.hugo` must be a mapping.``
-
-> ``package-build config: `site.hugo.baseURL` is derived from package.json `homepage` and must not be declared — it would be overwritten, and the two would disagree with nothing to say so.``
-
 `site.search` is whether the rendered site carries a search index. On by
-default: `package-build site-root` runs Pagefind over the rendered pages after
+default: `package-build site build` runs Pagefind over the rendered pages after
 it writes `_headers`, and the index lands beside them as
 `build/site/<contentPackage>/pagefind/`, served at `/<contentPackage>/pagefind/`
 with the rest of the site. The theme loads it relative to the site's base URL
@@ -1147,30 +1130,157 @@ site:
 
 > ``package-build config: `site.maps` must be a boolean.``
 
-### The generated Hugo configuration
-
-`package-build site` writes `build/hugo/hugo.toml` on every run. Every value
-in it has one source, and that source is where it is edited:
-
-| Key                               | Derived from                                                                                                                                            |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `baseURL`                         | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`                                                     |
-| `title`                           | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                     |
-| `locale`                          | the organisation's locale, `en-us`, in `engine/site-config.mjs`                                                                                         |
-| `publishDir`                      | `contentPackage`, under the deployment root `build/site` — written relative to `build/hugo/`, so `../site/<contentPackage>`                             |
-| `contentDir`                      | the fixed content mount, `build/hugo/content` — written as `content`                                                                                    |
-| `themesDir`                       | this package's own root, which holds the theme it ships, written relative to `build/hugo/`                                                              |
-| `theme`                           | the theme's directory inside this package, `hugo-theme`                                                                                                 |
-| `disableKinds`                    | the toolchain, which renders a site as its homepage and its pages: `["section", "taxonomy", "term", "RSS"]` on every site, whatever its notes carry     |
-| `taxonomies`                      | the toolchain — never written, because `taxonomy` and `term` are disabled kinds                                                                         |
-| `outputs`                         | the toolchain — never written, because every listing kind is disabled                                                                                   |
-| `params.description`              | `site.description`, which is required                                                                                                                   |
-| `params.author`                   | the first entry of `authors`, its `name`; absent when `authors` is empty                                                                                |
-| `params.cdnBaseURL`               | `site.assets`, which is required                                                                                                                        |
-| `params.brand`                    | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                       |
-| `params.notfound`                 | `site.notfound`; absent when undeclared                                                                                                                 |
-| `markup.goldmark.renderer.unsafe` | the toolchain, whose pages carry raw HTML — a `<figure>` for every image, a `<span>` marking an unresolved link                                         |
-| `menu`                            | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as `parent` entries |
+#### Where a site is served, and what it lists
+
+`site.base` is the path the site is served at. Unset, a package's site is
+served at `/<contentPackage>/`; a value begins and ends with `/`, and `/`
+serves the site at the root of its origin, as heroiclands.org's own site is.
+`package.json`'s `homepage` is then that path on the origin (see
+[`homepage`](#homepage)), and `package-build site build` writes the site at
+that path under the deployed root — at `build/site/` itself for `/`:
+
+> ``package-build config: `site.base` is `blog/`; it is the path the site is served at, which begins and ends with `/` — `/` for the root of the origin.``
+
+`site.sections` publishes a note as a section's page. Each key is a section's
+name, published at `/<name>/`, and each value is the address of the note that
+is its page, written `<type>-<shortcode>`. The note keeps its title, its
+description and its body, and is published at the section rather than at its
+own address, so every link to it reaches `/<name>/`. A section's page lists
+the pages of its section that its body does not already link.
+
+```yaml
+site:
+  sections:
+    blog: doc-blog
+    projects: doc-projects
+```
+
+A name is one address segment, and no section claims a path the site writes
+itself — `tags`, `css`, `js`, `fonts`, `img` or `pagefind`. A value is a note's
+address, never the homepage's, and no note is the page of two sections. A
+section whose note is missing from the content tree fails the build, located
+at its value:
+
+> ``package-build config: `site.sections` must be a mapping of a section's name to the address of the note that is its page.``
+
+> ``package-build config: `site.sections.the-blog` names the section `the-blog`, which is published at `/the-blog/` and so is one address segment: lowercase letters and digits.``
+
+> ``package-build config: `site.sections.tags` names the section `tags`, a path the site writes itself (tags, css, js, fonts, img, pagefind).``
+
+> ``package-build config: `site.sections.blog` is `Blog`; it is the address of the note that is the section's page, written `<type>-<shortcode>`, such as `doc-blog`.``
+
+> ``package-build config: `site.sections.blog` is `homepage-root`, and the homepage is the site's front page, not a section's.``
+
+> ``package-build config: `site.sections.news` is `doc-blog`, which is already the page of `blog`.``
+
+> `` `site.sections.projects` is `doc-plans`, and no note in the content tree has that address, so the section has no page to publish at `/projects/`. ``
+
+`site.feed` names the section the site's posts are published in. A post is a
+`doc` of `subType: post` (see the
+[`doc` reference](reference/note-types.md#doc)); with `site.feed` set, every
+post is a page of that section, which lists them newest first by their
+`data.date`, and the section's posts are written as an Atom feed at
+`/<section>/atom.xml`, newest first, which every page links in its head. Each
+entry names the post's `data.author`, or the site's byline where the post
+names none. The section may be one `site.sections` gives a page; one it does
+not is titled by its name. Without `site.feed` a post is a page in no section,
+and the site has no feed:
+
+```yaml
+site:
+  sections:
+    blog: doc-blog
+  feed: blog
+```
+
+> ``package-build config: `site.feed` names the section `blog/atom.xml`, which is published at `/blog/atom.xml/` and so is one address segment: lowercase letters and digits.``
+
+`site.tags` writes a page for each tag the site's pages carry, at
+`/tags/<tag>/`, listing the pages that carry it, and an index of every tag
+with how many pages carry it at `/tags/`. A page's tags then link to their
+pages. Off by default, when a page's tags are shown and link nowhere:
+
+> ``package-build config: `site.tags` must be a boolean.``
+
+`site.sitemaps` names the package sites, by `contentPackage`, whose sitemaps
+the site's sitemap index lists. It belongs to a site served at the root of an
+origin: the build writes `sitemap-index.xml`, naming the site's own
+`sitemap.xml` and `/<package>/sitemap.xml` on the same origin for each one
+named, and `robots.txt`, naming the index and every sitemap in it. Every site
+writes its own `sitemap.xml` whether or not it states this key.
+
+```yaml
+site:
+  base: /
+  sitemaps: [sohl, hm3, thalorna, kethira, thalornaaltart, harnensemble, harnadventures]
+```
+
+`site.mergeIndexes` names the package sites, by `contentPackage`, whose search
+indexes the site's own search reads beside its own, so one search box finds
+the pages of every site named. Each is read from `/<package>/pagefind/` on the
+site's own origin, which is where that package's site publishes its index, so
+the merge resolves where the sites share an origin — at heroiclands.org,
+through its routing Worker — and not on a site served alone, such as by
+`site serve`. Name only a package site whose `site.search` is on; one that
+publishes no index leaves the search with an index it cannot load.
+
+```yaml
+site:
+  mergeIndexes: [sohl, thalorna, kethira, harnensemble]
+```
+
+An entry of either list is a package's `contentPackage`, named once, and
+never the site's own:
+
+> ``package-build config: `site.sitemaps` must be a list of package sites, each named by its `contentPackage`.``
+
+> ``package-build config: `site.sitemaps[1]` is `harn-adventures`, which is not a package site: name one by its `contentPackage`, lowercase letters and digits.``
+
+> ``package-build config: `site.mergeIndexes[2]` names `sohl` more than once.``
+
+> ``package-build config: `site.sitemaps[0]` is `heroiclands`, this site's own package.``
+
+Each is refused where it cannot mean anything — a sitemap index on a site not
+at the root of its origin, and a merged search on a site with no search:
+
+> ``package-build config: `site.sitemaps` names the package sites a sitemap index lists, and a sitemap index and `robots.txt` belong at the root of an origin; this site is served at `/thalorna/`, so declare `site.base: /` or drop the key.``
+
+> ``package-build config: `site.mergeIndexes` names the search indexes this site's search reads beside its own, and `site.search` is `false`, so there is no search to read them.``
+
+heroiclands.org's own site states them all:
+
+```yaml
+contentPackage: heroiclands
+packageKind: documentation
+site:
+  base: /
+  sections:
+    blog: doc-blog
+    projects: doc-projects
+  feed: blog
+  tags: true
+  sitemaps: [sohl, hm3, thalorna, kethira, thalornaaltart, harnensemble, harnadventures]
+  mergeIndexes: [sohl, thalorna, kethira, harnensemble]
+```
+
+### What the site build reads
+
+`package-build site build` composes the site's settings from sources the
+repository already states, a few constants of the organisation, and the
+navigation `deps fetch` cached. Every value has one source, and that source is
+where it is edited:
+
+| Setting              | Derived from                                                                                                                                          |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| base URL             | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`                                                   |
+| title                | `site.title` when declared, otherwise `packageBuild.manifest.title`                                                                                   |
+| `params.description` | `site.description`, which is required                                                                                                                 |
+| `params.author`      | the first entry of `authors`, its `name`; absent when `authors` is empty                                                                              |
+| `params.cdnBaseURL`  | `site.assets`, which is required                                                                                                                      |
+| `params.brand`       | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`                                                     |
+| `params.notfound`    | `site.notfound`; absent when undeclared                                                                                                               |
+| `params.scriptFonts` | the installed script fonts' stylesheet, present only when the package delivers fonts                                                                  |
+| menu                 | the navigation `package-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as its `children` |
 
 The site build reads the navigation from the cache only. A cold cache is an
 error naming the command that fills it:
@@ -1192,13 +1302,10 @@ build the same way:
 
 > ``package-build config: `site.assets` is not declared, and a site build needs one — it is the host every package's imagery is served from, and the theme resolves every relative asset against it.``
 
-Nothing else is emitted. `home` and `page` are the only kinds a site
-renders: the homepage is the mount's `_index.md`, every note is a page, and
-`section`, `taxonomy`, `term` and `RSS` are disabled on every site — so no
-`[taxonomies]` or `[outputs]` is written, Hugo's default taxonomy pair never
-applies, and a note's `tags:` reach the page's front matter and nothing
-else. A tag is a field a content table filters on, not a page of its own.
-Every other key is `site.hugo`'s to add.
+Nothing else is configurable. A site is its homepage and its pages: the
+homepage is the package root and every note is a page. A tag is a field a
+content table filters on; a note's `tags:` reach its page and nothing else
+unless `site.tags` writes a page for each.
 
 ### `pdf`
 
@@ -1748,7 +1855,7 @@ end in a slash when set (a missing one would silently fuse the prefix to
 the first section) and must not begin with one (which would make the
 recorded address package-absolute):
 
-The site build uses this prefix for its Hugo source mount. Published note
+The site build mounts the content tree at this prefix. Published note
 addresses and content-index paths stay relative to the package root; the
 manifest's package homepage also stays at that root. A page staged under
 `kb/` can therefore publish at `/<contentPackage>/<type>-<shortcode>/`.
@@ -1987,7 +2094,9 @@ names a layer or none at all, with no specificity contest and no
 `!important`. The term column, the gutter and the width at which the list
 stacks are custom properties — `--pb-deflist-term-width`,
 `--pb-deflist-gutter` and `--pb-deflist-row-gap` — so a package adjusts them
-without copying the rule.
+without copying the rule. `--pb-rubric` is the red a rubric script's emphasis
+is set in, `light-dark(#9c281b, #e0705f)`; see
+[emphasis in a script](reference/theme-pages.md#emphasis-in-a-script).
 
 Declare `false` to decline it; nothing is staged and nothing is added to
 `styles`:
@@ -2254,16 +2363,15 @@ the source directory:
 
 ## Every forbidden key, in one place
 
-| Key                                                                                                                                                                                                                                                                                         | Why                                                                                                                                                    |
-| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `rootDir`                                                                                                                                                                                                                                                                                   | Forbidden in a YAML configuration — always the file's own directory.                                                                                   |
-| `foundryPackage`                                                                                                                                                                                                                                                                            | Forbidden in a YAML configuration — always the adjacent `package.json` `name`.                                                                         |
-| `homepage`                                                                                                                                                                                                                                                                                  | Forbidden in a YAML configuration — always the adjacent `package.json`'s own `homepage`.                                                               |
-| `author`                                                                                                                                                                                                                                                                                    | Refused as an unknown key — the byline is the first entry of [`authors`](#authors).                                                                    |
-| `packageBuild.manifest.authors`                                                                                                                                                                                                                                                             | Forbidden — derived from [`authors`](#authors), without each entry's `role`.                                                                           |
-| `stats.systemId`                                                                                                                                                                                                                                                                            | Forbidden in every configuration — derived from `packageKind`, `requiresSystem` or a lone declared system.                                             |
-| `stats.systemVersion`                                                                                                                                                                                                                                                                       | Forbidden in every configuration — derived from `package.json` (a system) or `systems:` / `relationships.systems` (a module).                          |
-| `packageBuild.manifest.id`, `.version`, `.description`, `.url`, `.bugs`, `.manifest`, `.download`, `.compatibility`, `.relationships`, `.packs`                                                                                                                                             | Forbidden — each is derived from `package.json` or the top level of `package-build.config.yaml`; see [`packageBuild.manifest`](#packagebuildmanifest). |
-| `site.hugo.baseURL`, `.title`, `.locale`, `.publishDir`, `.contentDir`, `.themesDir`, `.theme`, `.disableKinds`, `.taxonomies`, `.outputs`, `.params.description`, `.params.author`, `.params.cdnBaseURL`, `.params.brand`, `.params.notfound`, `.markup.goldmark.renderer.unsafe`, `.menu` | Forbidden — each is written by the site build from a source it names; see [the generated Hugo configuration](#the-generated-hugo-configuration).       |
-| `publish.site` (any value)                                                                                                                                                                                                                                                                  | Refused — publication follows the authored content tree.                                                                                               |
-| `packs`, `itemBuilders`, `docs`, `compatibility`, `relationships`, `systems`, `requiresSystem`, `stats`, `foundryPackage`                                                                                                                                                                   | Forbidden in a `documentation` package — each describes a Foundry package this kind is not; see the key's own section for its located refusal message. |
+| Key                                                                                                                                             | Why                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `rootDir`                                                                                                                                       | Forbidden in a YAML configuration — always the file's own directory.                                                                                   |
+| `foundryPackage`                                                                                                                                | Forbidden in a YAML configuration — always the adjacent `package.json` `name`.                                                                         |
+| `homepage`                                                                                                                                      | Forbidden in a YAML configuration — always the adjacent `package.json`'s own `homepage`.                                                               |
+| `author`                                                                                                                                        | Refused as an unknown key — the byline is the first entry of [`authors`](#authors).                                                                    |
+| `packageBuild.manifest.authors`                                                                                                                 | Forbidden — derived from [`authors`](#authors), without each entry's `role`.                                                                           |
+| `stats.systemId`                                                                                                                                | Forbidden in every configuration — derived from `packageKind`, `requiresSystem` or a lone declared system.                                             |
+| `stats.systemVersion`                                                                                                                           | Forbidden in every configuration — derived from `package.json` (a system) or `systems:` / `relationships.systems` (a module).                          |
+| `packageBuild.manifest.id`, `.version`, `.description`, `.url`, `.bugs`, `.manifest`, `.download`, `.compatibility`, `.relationships`, `.packs` | Forbidden — each is derived from `package.json` or the top level of `package-build.config.yaml`; see [`packageBuild.manifest`](#packagebuildmanifest). |
+| `publish.site` (any value)                                                                                                                      | Refused — publication follows the authored content tree.                                                                                               |
+| `packs`, `itemBuilders`, `docs`, `compatibility`, `relationships`, `systems`, `requiresSystem`, `stats`, `foundryPackage`                       | Forbidden in a `documentation` package — each describes a Foundry package this kind is not; see the key's own section for its located refusal message. |

package/docs/content-format.md

@@ -31,7 +31,7 @@ Leading `:` captions describe the next supported block; `:@` captions also numbe
 
 A code fence with language `verse` keeps verse lines, stanza breaks and relative indentation. Its numbered caption uses the **Poem** label. Generic `:::` divs and `[inline spans]{.class}` accept attributes. See [verse](authoring/links-and-markup.md#verse), [fenced divs](authoring/links-and-markup.md#fenced-divs) and [inline spans](authoring/links-and-markup.md#inline-spans). `numstep=N` numbers every Nth line. `col1=` and `col2=` set the poem in at most two columns, each a `:`-joined stack of `language[/mapping[/font]]` entries, the first in the normal tone and the rest in grey; with columns, each blank-line group of `[text]{lang=…}` spans is one verse line, every entry sets the span in its language, and a `***` line breaks the stanza. See [verse in columns](authoring/links-and-markup.md#verse-in-columns).
 
-A span, a generic div or a verse fence marks its text's language with `lang=`, the font it is set in with `font=` and a mapping with `map=`, each optional, and the runs inside a div or a fence inherit its keys. `lang=` is a name the package declares in `languages` or a BCP 47 tag, and gives the language tag alone. `font=` is a face of the installed `@heroiclands/fonts`, named by its class without `hl-`, or `mono`, `serif` or `sans`. `map=` names a mapping note: a `doc` note whose `data.map` lists the fonts it is drawn in and rows that rewrite the text before it is set, a font's own rows first. With `lang=` naming a language whose configured `note` names its language note, a word whose entry states a `native` form for the map is written by it, and the rows spell every other word. Every word of such a run is a lexicon form, a word of a name the language note's own register lists under a tongue other than `translation`, or a form a plural row, the verb pattern or an affix stating `replaces` derives from a lexicon form, and any other word is an error at the word. A character a face does not draw, after the map, is an error at the character it came from. Text with a font, a map or a declared language is plain. Every marked construct is a row of the `runs` relation, every mapping row of the `maps` relation, and every native form of the `natives` relation. See [marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
+A span, a generic div or a verse fence marks its text's language with `lang=`, the font it is set in with `font=` and a mapping with `map=`, each optional, and the runs inside a div or a fence inherit its keys. `lang=` is a name the package declares in `languages` or a BCP 47 tag, and gives the language tag alone. `font=` is a face of the installed `@heroiclands/fonts`, named by its class without `hl-`, or `mono`, `serif` or `sans`. `map=` names a mapping note: a `doc` note whose `data.map` lists the fonts it is drawn in and rows that rewrite the text before it is set, a font's own rows first. With `lang=` naming a language whose configured `note` names its language note, a word whose entry states a `native` form for the map is written by it, and the rows spell every other word. A map stating `logographic: true` spells no word by its rows: each word is written by its own `native` entry or its parts' writings, and a word with neither, or whose form stands for entries written differently, is a located error. Every word of such a run is a lexicon form, a word of a name the language note's own register lists under a tongue other than `translation`, or a form a plural row, the verb pattern or an affix stating `replaces` derives from a lexicon form, and any other word is an error at the word. A character a face does not draw, after the map, is an error at the character it came from. A verse fence that states `scan=` (the `name` of a `data.metres` entry of a `doc` note) with a `lang=` whose language note states `data.sounds.stress` is counted line by line by the beat convention, and a line that cannot have the metre's beats is a warning at the line; see [metres](reference/format-details.md#metres). Text with a font, a map or a declared language is plain, except that text set in a face takes `*…*` and `**…**`: they render by the convention its language note's `data.emphasis` states, else the one the script note listing its face states in `data.script` (`rubric` or `overline`), else plainly, and a language whose `data.emphasis` is `words` makes them an error. Every marked construct is a row of the `runs` relation, every mapping row of the `maps` relation, and every native form of the `natives` relation. See [marking language, font and mapping](authoring/links-and-markup.md#marking-language-font-and-mapping).
 
 Mark a name without a note as `[Name]{.name data-type="being"}`; the optional
 classification uses the declared note vocabulary. The [name-marking
@@ -175,6 +175,6 @@ Places, affiliations, lore and beings may name their culture in `data.culture`,
 
 An affiliation may name the trade, temple or order tongue it keeps in its own `data.language`. An affiliation that reaches no culture is a warning, in a tree holding a culture note. A language needs no culture and no affiliation. See [type: affiliation](reference/format-details.md#type-affiliation).
 
-A language note (`type: skill`, `subType: language`) states its words in frontmatter: `data.words` states each word as a map of its form, class, field and gloss — one sense or a list of them, which a dictionary numbers — with its source, its variant forms, the pieces it is built from and a note, beside `data.classModifiers`, `data.fields` and `data.affixes`, each affix with the `kind` it makes, for a given name's ending who the name is `given` to, and the stem closes it is barred after; a zero affix states `zero: true` and no form. The notes a word is cited from are derived, not written: a note cites a word by marking it in italics in its prose, matched by form or a variant with diacritics and case set aside. The language of a word is the note it sits on, and none of it reaches the compiled Item. A daughter language names its parent in `data.family` and reads the parent's words as its own; the `language_lineage` relation joins a language to its ancestors. Classes come from the [master word classes](reference/format-details.md#word-classes). A culture or an affiliation states its own glossary entries in `data.glossary`: common words in its core vocabulary, dictionary words with a context meaning, or phrases, compounds and terms of art outside the dictionary with their own gloss. An entry naming a word of its resolved language takes the word's senses and class and links to its language entry; a `definition` supplies the entry's meaning instead. Common marks belong to the glossary's owner. A language note with nonempty `data.words` receives its full Dictionary section automatically: one alphabetical list with field tags and one key. A culture or affiliation with nonempty `data.glossary` receives only its explicitly declared entries in its Glossary section; ranks and offices stand in the affiliation's own sections. A note without the relevant frontmatter receives no such section. All surfaces show these sections after the authored text, or under an existing `{#dictionary}`, `{#lexicon}` or `{#glossary}` heading after its introduction. There are no setting-wide dictionary or glossary pages. Every entry resolves to a language — its own `language`, else the affiliation's, its parents' or its culture's, else the culture's — or is an error at the entry. The `words`, `affixes`, `fields`, `glossary` and `language_lineage` relations hold them for `sql` fences, the `dictionary` relation lists each word under every language that has it, inherited words included, and the `terms` relation each glossary entry, rank and office with its culture associations; a fence sets custom views with `layout=dictionary` or `layout=glossary`. A language note names the tag a dictionary prints for it in `data.abbreviation`. Every fact a check reads about a language's names, sounds and history is frontmatter too: `data.tongues` and `data.register` (every name the setting gives in the language's reach, the notes carrying each derived from the index, and a name tagged `other:<tongue>` or `exonym:<tongue>` one that the tongue's own language note registers under that tongue), `data.retired`, `data.scope`, `data.sounds` (letters with their place, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule, syllable finals, syllable rules and vowel harmony with each vowel's front partner, the joining of parts, written marks, a root's skeleton vowel and frames, the spellings read past, and named mutations such as wearing and voicing), `data.soundChanges` (named sets of ordered steps), `data.elements` (each standing `opening`, `closing`, `either` or `link`, for one kind of name, with the word it is the stem of and its joining form), `data.roots`, `data.cognates` (with a reconstructed `proto` form), `data.callingNames`, `data.older` (the forms older than the rules), `data.negation` (the negative particle and the mutation it brings) and `data.naming` (how long each class of name runs, the edges names keep that words do not, the element kinds each kind of name draws on, what a place name takes from what it is held from, and the near name), each a relation — `sounds` as `letters`, `edges`, `clusters`, `cluster_groups`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past` and `mutations`, `soundChanges` as `sound_changes`, `callingNames` as `calling_names` — that a fence sets back on the page. A word's citations also come from a note whose name, alias or rank or office title spells it whole. See [a language's words](reference/format-details.md#a-languages-words), [a language's register, sounds and history](reference/format-details.md#a-languages-register-sounds-and-history), [glossary terms](reference/format-details.md#glossary-terms) and [dictionaries and glossaries](reference/format-details.md#dictionaries-and-glossaries).
+A language note (`type: skill`, `subType: language`) states its words in frontmatter: `data.words` states each word as a map of its form, class, field and gloss — one sense or a list of them, which a dictionary numbers — with its source, its variant forms, the pieces it is built from and a note, beside `data.classModifiers`, `data.fields` and `data.affixes`, each affix with the `kind` it makes, for a given name's ending who the name is `given` to, and the stem closes it is barred after; a zero affix states `zero: true` and no form. The notes a word is cited from are derived, not written: a note cites a word by marking it in italics in its prose, matched by form or a variant with diacritics and case set aside. The language of a word is the note it sits on, and none of it reaches the compiled Item. A daughter language names its parent in `data.family` and reads the parent's words as its own; the `language_lineage` relation joins a language to its ancestors. Classes come from the [master word classes](reference/format-details.md#word-classes). A culture or an affiliation states its own glossary entries in `data.glossary`: common words in its core vocabulary, dictionary words with a context meaning, or phrases, compounds and terms of art outside the dictionary with their own gloss. An entry naming a word of its resolved language takes the word's senses and class and links to its language entry; a `definition` supplies the entry's meaning instead. Common marks belong to the glossary's owner. A language note with nonempty `data.words` receives its full Dictionary section automatically: one alphabetical list with field tags and one key. A culture or affiliation with nonempty `data.glossary` receives only its explicitly declared entries in its Glossary section; ranks and offices stand in the affiliation's own sections. A note without the relevant frontmatter receives no such section. All surfaces show these sections after the authored text, or under an existing `{#dictionary}`, `{#lexicon}` or `{#glossary}` heading after its introduction. There are no setting-wide dictionary or glossary pages. Every entry resolves to a language — its own `language`, else the affiliation's, its parents' or its culture's, else the culture's — or is an error at the entry. The `words`, `affixes`, `fields`, `glossary` and `language_lineage` relations hold them for `sql` fences, the `dictionary` relation lists each word under every language that has it, inherited words included, and the `terms` relation each glossary entry, rank and office with its culture associations; a fence sets custom views with `layout=dictionary` or `layout=glossary`. A language note names the tag a dictionary prints for it in `data.abbreviation`. A `doc` note states a setting's core concepts in `data.concepts`, a language note says it must cover them with `data.core: true`, and a word names the concepts it serves in `concept`; `package-build core` lists what each covering language has no word for (see [the core vocabulary](reference/format-details.md#the-core-vocabulary)). Every fact a check reads about a language's names, sounds and history is frontmatter too: `data.tongues` and `data.register` (every name the setting gives in the language's reach, the notes carrying each derived from the index, and a name tagged `other:<tongue>` or `exonym:<tongue>` one that the tongue's own language note registers under that tongue), `data.retired`, `data.scope`, `data.sounds` (letters with their place, word edges from a closed list, the cluster limit and the groups of clusters inside a word, the stress rule (`two`, `longer` and `mark`), syllable finals, syllable rules and vowel harmony with each vowel's front partner, the joining of parts, written marks, a root's skeleton vowel and frames, the spellings read past, and named mutations such as wearing and voicing), `data.soundChanges` (named sets of ordered steps), `data.elements` (each standing `opening`, `closing`, `either` or `link`, for one kind of name, with the word it is the stem of and its joining form), `data.roots`, `data.cognates` (with a reconstructed `proto` form), `data.callingNames`, `data.older` (the forms older than the rules), `data.negation` (the negative particle and the mutation it brings) and `data.naming` (how long each class of name runs, the edges names keep that words do not, the element kinds each kind of name draws on, what a place name takes from what it is held from, and the near name), each a relation — `sounds` as `letters`, `edges`, `clusters`, `cluster_groups`, `stress`, `finals`, `syllables`, `joining`, `joins`, `marks`, `skeleton`, `frames`, `read_past` and `mutations`, `soundChanges` as `sound_changes`, `callingNames` as `calling_names` — that a fence sets back on the page. A word's citations also come from a note whose name, alias or rank or office title spells it whole. See [a language's words](reference/format-details.md#a-languages-words), [a language's register, sounds and history](reference/format-details.md#a-languages-register-sounds-and-history), [glossary terms](reference/format-details.md#glossary-terms) and [dictionaries and glossaries](reference/format-details.md#dictionaries-and-glossaries).
 
 Blockquote alerts use `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, or `[!]`, with optional attributes after the marker. They replace the former info and warn div fences; secret blocks remain supported. See [alerts](authoring/links-and-markup.md#alerts).

package/docs/diagnostics.md

@@ -330,7 +330,7 @@ lint`, `package-build lang check`, `package-build lang coverage`,
 and returns only the count whose `severity` is `error`, and the command sets
 `process.exitCode = 1` exactly when that count is nonzero. Commands whose
 findings are hand-assembled — `package-build links`, `package-build
-reachability`, `package-build site`, `package-build package compile` — apply
+reachability`, `package-build site build`, `package-build package compile` — apply
 the same rule by construction: everything they can report is a broken
 address, a dead link or a document Foundry would silently drop a field from,
 so every finding they emit is already `severity: "error"` and any finding at
@@ -368,7 +368,7 @@ over one would teach people to stop reading the report.
 | `package-build addresses diff --from <artifact>` | the corpus cannot be indexed (always); otherwise only with `--strict`, and only then are the address findings `error`-severity                                                                                                                                     |
 | `package-build format [paths..]`                 | a file it checked is not formatted (or, under `--write`, could not be brought to a fixpoint) — never on a shared-convention divergence, which is always advisory                                                                                                   |
 | `package-build markdown [paths..]`               | it reports any markdownlint finding                                                                                                                                                                                                                                |
-| `package-build site`                             | any gate finding (no homepage, a wikilink in frontmatter, an address that cannot be derived, an unusable or unaddressable foreign manifest, a conflicting address) or any table or wikilink error while writing pages — the run stops at the first gate that fires |
+| `package-build site build`                       | any gate finding (no homepage, a wikilink in frontmatter, an address that cannot be derived, an unusable or unaddressable foreign manifest, a conflicting address) or any table or wikilink error while writing pages — the run stops at the first gate that fires |
 | `package-build pdf`                              | it could not build the book for a reason other than a deliberate no-op — never on a reported finding by itself                                                                                                                                                     |
 | `package-build map`                              | `--tree` reports an `error`-severity finding (a place with no parent, a parent that does not resolve, a cycle), a named place is not one, the renderer fails, or the corpus cannot be indexed — never on a warning                                                 |
 | `package-build docs item-fields --check`         | the generated page differs from what is committed                                                                                                                                                                                                                  |

package/docs/getting-started.md

@@ -15,7 +15,7 @@ subType: userguide
 | A Foundry module, with or without source code | [Module project](guides/module-project.md) |
 | Notes in an existing package                  | [Your first note](authoring/first-note.md) |
 
-Node 24 or newer and npm are needed for the toolchain. The generated website build uses Hugo Extended; the book build uses Typst. A Foundry installation and deployment credentials are not needed to author or build content locally.
+Node 24 or newer and npm are needed for the toolchain. The book build uses Typst. A Foundry installation and deployment credentials are not needed to author or build content locally.
 
 ## Start a package
 

package/docs/guides/icons.md

@@ -130,7 +130,7 @@ Run the content lint and build the surfaces the package publishes:
 ```bash
 package-build lint
 package-build package compile
-package-build site
+package-build site build
 package-build pdf --no-compile
 ```
 

package/docs/guides/module-project.md

@@ -25,7 +25,7 @@ npm run lint
 The generated project includes a homepage, an introduction, a website build,
 and a book build. Run `npm run build:site` to produce the site,
 `npm run serve:site` to view it locally, or `npm run build:book` for a PDF.
-Those commands require Hugo Extended and Typst respectively. Run
+The book build requires Typst. Run
 `package-build init --check` to inspect the project without changing it. See
 [`init`](../commands.md#package-build-init-directory) for the package kinds,
 interactive prompts, and collision rules.
@@ -891,11 +891,8 @@ address to `package.json` as `homepage`, with a `description` beside it, list
 the package's people in `authors` in `package-build.config.yaml`, and add a
 `packageBuild.manifest.title`. The theme the site renders
 through ships with this package, so nothing else is installed. Then `package-build deps fetch` caches the
-organisation's navigation, and `package-build site` writes the whole Hugo
-source tree under `build/hugo/` — the configuration generated from those
-values, and the content mount — for `hugo --source build/hugo` to render
-into `build/site/<contentPackage>/`. There is no Hugo configuration to
-write: the file is generated on every run, and what is genuinely the
+organisation's navigation, and `package-build site build` renders the site
+into `build/site/<contentPackage>/` from those values. What is genuinely the
 package's own — the wording of its "page not found" page — goes in the
 `site:` block as `site.notfound`. The same command publishes the content tree's
 every page beside the homepage — one
@@ -935,7 +932,7 @@ Everything in steps 4 and 8 that exists to describe a Foundry package is
 tree supplies its site pages and book entries.
 
 So a documentation package's configuration is steps 1 through 6 with a different
-`packageKind`, plus a `site:` block, and then `package-build site` in place of
+`packageKind`, plus a `site:` block, and then `package-build site build` in place of
 steps 7 through 11. [`configuration.md`](../configuration.md) carries the refusal
 message for every key; [`commands.md`](../commands.md) covers the two commands such
-a package lives on, `package-build site` and `package-build pdf`.
+a package lives on, `package-build site build` and `package-build pdf`.

package/docs/guides/release-and-deploy.md

@@ -199,9 +199,9 @@ desk:
 - **`npm run build`** runs `package-build ci`: the Build & Test workflow's
   `run:` steps in a `linux/amd64` container over a clean export of `HEAD`.
   `npm run build -- --native` runs them on the host in the working tree instead.
-  Off Linux, the Typst, GraphViz and Hugo steps install nothing; each uses the
+  Off Linux, the Typst and GraphViz steps install nothing; each uses the
   tool already on `PATH` and stops with `<tool> is not on PATH` when it is
-  missing, so a Mac running `--native` needs `typst`, `dot` and Hugo extended
+  missing, so a Mac running `--native` needs `typst` and `dot`
   installed first.
 - **`npm run deploy:npm`** runs `npm publish`. Provenance is attested only on a
   CI runner that can mint a Sigstore identity — GitHub Actions with an OIDC