@heroiclands/package-build 22.23.0 → 22.24.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @heroiclands/package-build
 
+## 22.24.0
+
+### Minor Changes
+
+**Hero banners** — A page whose note names its own hero image shows that image, in place of the stock banner for its kind; a note naming none gets a band with no image.
+
+**Figures** — A numbered figure, table, listing or map reads as one block, its number and caption set beneath it rather than running on as body text, and a passage set apart as an aside draws as a box.
+
+**Pictures** — A portrait or an emblem draws at half the content column and a banner, plate or map at its full width, never wider than the size the picture was made at; a stated width still overrides the role's measure.
+
+**Installing** — The shared Hugo theme arrives with this package, so a site declares this package alone and needs no separate theme dependency.
+
+**Hero images** — The authoring guide states the three states of a note's hero image: a picture, a deliberate blank that declines one, and an absent key that takes the default for the note's type.
+
 ## 22.23.0
 
 ### Minor Changes

package/README.md

@@ -33,6 +33,7 @@ The documentation lives in the Markdown files in this repository. Start with [th
 | Detailed format rules and examples                | [Format details](docs/reference/format-details.md)           |
 | Compendium routing and document builds            | [Packs](docs/guides/packs.md)                                |
 | Website build and publication                     | [Site](docs/guides/site.md)                                  |
+| What the theme draws on a page                    | [Theme pages](docs/reference/theme-pages.md)                 |
 | PDF book build                                    | [Book](docs/guides/book.md)                                  |
 | Icon generation and use                           | [Icons](docs/guides/icons.md)                                |
 | Reference pages and content indexes               | [Reference pages](docs/guides/reference-pages.md)            |

package/docs/authoring/assets.md

@@ -38,6 +38,21 @@ role: portrait
 
 **A hero image is 1792×768.** `data.banner` fills one fixed strip wherever it is drawn, so every banner is cut to that size and a picture of any other size is a finding naming both sizes — resize the picture to match. That is the one size any art field requires. A map's `bgImage` sets its own scene's dimensions, so that asks nothing of a picture's dimensions either.
 
+`data.banner` reads in one of three states:
+
+| A note writes      | The page draws                                     |
+| ------------------ | -------------------------------------------------- |
+| an asset Address   | that picture                                       |
+| a blank            | no picture, on purpose, and no default replaces it |
+| nothing, or `null` | a default picture chosen by the note's `type`      |
+
+Omitting the key does not mean "no hero image" — it means artwork chosen for
+the author, which inverts the ordinary reading of an absent key. **A note
+declines with a blank, not with `none`.** `none` parses as an ordinary asset
+Address — a shortcode, not a keyword — and since nothing in the corpus
+answers to it, the build drops the key outright and the page falls through to
+its type's default: the opposite of a decline.
+
 `role` is one of `portrait`, `emblem`, `banner`, `plate` or `map`, and belongs to the `image` type only — declaring it in a `provenance.yaml` under `assets/icons` is a finding, since an icon carries one nominal size per medium whatever the file holds. Leave the key out for an ordinary picture; there is no default role name, only its absence.
 
 **A role decides how large a picture written in prose draws, when nothing else states a size.** Each medium maps a role to a maximum, and the drawn size is the smaller of that slot and what the file's own pixels support — see [what a role draws at](../reference/format-details.md#what-a-role-draws-at). A named `size=` beside the embed still overrides it outright; an icon draws at the medium's nominal icon size whatever role it might otherwise have had, because `role` never reaches an icon address at all.

package/docs/commands.md

@@ -885,8 +885,8 @@ Install it with `npm ci`, which resolves from the lockfile this just moved.
 ```
 
 ```
-$ package-build bump @heroiclands/hugo-theme --check
-@heroiclands/hugo-theme  0.5.0 → 0.6.0
+$ package-build bump @heroiclands/package-build --check
+@heroiclands/package-build  22.6.0 → 22.7.0
 
 Run without --check to take it.
 ```
@@ -2310,9 +2310,9 @@ Three things are written, and nothing outside `build/`:
 - `build/hugo/hugo.toml`, generated on every run from `package.json`
   (`homepage`, `description`, `author`), `package-build.config.yaml`
   (`packageBuild.manifest.title`, `site.assets`, `site.notfound`,
-  `site.hugo`), the organisation's constants, the installed
-  `@heroiclands/hugo-theme`'s location, and the navigation `deps fetch`
-  cached. Every value's source is listed under
+  `site.hugo`), the organisation's constants, the shared theme's own
+  location, and the navigation `deps fetch` cached. Every value's source is
+  listed under
   [the generated Hugo configuration](configuration.md#the-generated-hugo-configuration).
 - `build/hugo/content/`, the content mount — the homepage as its `_index.md`,
   and the content tree's pages flat below `publish.address.prefix`. Wiped on
@@ -2321,13 +2321,13 @@ Three things are written, and nothing outside `build/`:
   deployment root `package-build site-root` writes beside. Nothing Hugo
   reads lands in what is published.
 
-The configuration's sources are read before the output tree is touched, so
-a missing `homepage`, a cold navigation cache or an uninstalled theme fails
-with the previous site intact. Every gate is then checked and reported, and
-the run stops at the first that fires, ordered so the report names the cause
-rather than its symptoms — an unusable dependency manifest, reported after
-the links that failed because of it, would otherwise read as a pile of
-broken notes. Reads the content tree named by `paths.content`.
+The configuration's sources are read before the output tree is touched, so a
+missing `homepage` or a cold navigation cache fails with the previous site
+intact. Every gate is then checked and reported, and the run stops at the
+first that fires, ordered so the report names the cause rather than its
+symptoms — an unusable dependency manifest, reported after the links that
+failed because of it, would otherwise read as a pile of broken notes. Reads
+the content tree named by `paths.content`.
 
 **OPTIONS**
 
@@ -2336,13 +2336,12 @@ None.
 **EXIT STATUS**
 
 1 if `package.json` declares no `homepage`, or one that does not end
-`/<contentPackage>/`; if `packageBuild.manifest.title` is undeclared; if the
-navigation has not been fetched (`package-build deps fetch` fills the cache
-and is named in the message); or if `@heroiclands/hugo-theme` is not
-installed. 1 if any gate fires — no homepage or two competing for it, a
-frontmatter wikilink, an address that cannot be derived, a stale or
-unaddressable dependency manifest, an address published twice, a table that
-failed to expand, or a dead wikilink. Otherwise 0.
+`/<contentPackage>/`; if `packageBuild.manifest.title` is undeclared; or if
+the navigation has not been fetched (`package-build deps fetch` fills the
+cache and is named in the message). 1 if any gate fires — no homepage or two
+competing for it, a frontmatter wikilink, an address that cannot be derived,
+a stale or unaddressable dependency manifest, an address published twice, a
+table that failed to expand, or a dead wikilink. Otherwise 0.
 
 **EXAMPLES**
 

package/docs/configuration.md

@@ -1031,8 +1031,8 @@ in it has one source, and that source is where it is edited:
 | `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`                       | where `@heroiclands/hugo-theme` is installed, resolved the way Node resolves a package and written relative to `build/hugo/`                            |
-| `theme`                           | the installed `@heroiclands/hugo-theme`, so `hugo-theme`                                                                                                |
+| `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                                                                                   |
@@ -1049,10 +1049,6 @@ error naming the command that fills it:
 
 > `the site navigation has not been fetched. Run `package-build deps fetch` first.`
 
-A missing theme names the package to install:
-
-> `@heroiclands/hugo-theme is not installed anywhere above <rootDir> — add it to `devDependencies`and run`npm ci``
-
 The site needs a title from `site.title` or the package manifest:
 
 > ``package-build config: declare `site.title` or `packageBuild.manifest.title` for the site's title.``

package/docs/guides/module-project.md

@@ -863,8 +863,8 @@ None of them is needed to build a package.
 **A website.** Every package publishes one — at the least, the homepage note
 from step 5 — at `https://www.heroiclands.org/<contentPackage>/`. Add that
 address to `package.json` as `homepage`, with a `description` and an `author`
-beside it; add `@heroiclands/hugo-theme` under `devDependencies`; and add a
-`packageBuild.manifest.title`. Then `package-build deps fetch` caches the
+beside it, 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

package/docs/guides/site.md

@@ -132,6 +132,47 @@ fenced example remains literal. `site.passOptions` supplies that named pass's
 options. This is a package-specific extension point; keep the general note
 format and link behavior in the [content format](../content-format.md).
 
+## What an emitted page carries
+
+A theme reads the front matter `package-build site` writes: the note's own
+front matter, plus the values the build derives. Which is which matters,
+because an authored value under a derived key is discarded.
+
+The build always writes `title`, `slug`, `url`, `kbfolder`, `package` and
+`infoboxes`. `title` is the note's name, `url` is the page's address, and
+`slug` is that address's last segment. `package` names the package shipping the
+note. `infoboxes` is assembled from the note's own fields, so no note authors
+it and nothing in the note format accepts it.
+
+The build writes `resolvedDates`, `related`, `contains`, `held_by`, `holdings`
+and `map` only when it has something to write. A page with no links either way
+carries no `related`, and a place with no drawing carries no `map`.
+
+An authored `aliases`, `related`, `contains`, `held_by`, `holdings` or `map` is
+dropped. Each states a fact about the whole tree rather than about one note, so
+the build replaces whatever a note wrote.
+
+Artwork addresses are rewritten in place under `data`. A page's `data.icon`,
+`data.bgImage` and `data.banner` carry the URLs the site serves rather than the
+addresses the note authored, and there are four cases to tell apart:
+
+| The note writes              | The page carries |
+| ---------------------------- | ---------------- |
+| an address something answers | the resolved URL |
+| an address nothing answers   | no key at all    |
+| `null`                       | `null`           |
+| `""`                         | `""`             |
+
+An address nothing answers is deleted rather than written through, so an absent
+key is the ordinary case for a theme to render nothing against, and no page
+reaches a reader carrying a broken image source. The two empties are distinct
+and both survive: `null` is a note naming no art, where a default may apply,
+and `""` is a note refusing art, where no default may replace it.
+
+The build writes these keys; [what the theme draws](../reference/theme-pages.md)
+describes the panel each one feeds — the infobox, the hero band, the holdings
+and related cards, the place map, and search.
+
 ## Build and serve
 
 ```bash

package/docs/project-setup.md

@@ -309,10 +309,10 @@ the rendered pages for search into `build/site/<contentPackage>/pagefind/`;
 and `serve:site` does the first and then `hugo server` for a live preview.
 The repository carries no Hugo configuration of its own: `hugo.toml` is
 generated on every run from `package.json`, `package-build.config.yaml`, the
-installed `@heroiclands/hugo-theme` and the navigation `deps fetch` cached,
-and the only file to add is `@heroiclands/hugo-theme` under
-`devDependencies`. Hugo itself is a separate install — the extended edition,
-on the developer's `PATH` and the runner's.
+shared theme that ships with `@heroiclands/package-build`, and the navigation
+`deps fetch` cached — a site declares this one package and needs nothing
+further added for its theme. Hugo itself is a separate install — the
+extended edition, on the developer's `PATH` and the runner's.
 
 The site build reads the cached navigation, so `build:site` in a package with
 no other dependency still runs `deps fetch` first: