@heroiclands/package-build 23.1.0 → 23.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (248) hide show
  1. package/CHANGELOG.md +71 -0
  2. package/bin/content-commands.mjs +68 -149
  3. package/bin/package-build.mjs +56 -10
  4. package/ci/check-banners.mjs +42 -6
  5. package/ci/confirm-npm-version.mjs +135 -0
  6. package/ci/content-format-reference.mjs +14 -5
  7. package/config.mjs +1 -0
  8. package/container.mjs +185 -4
  9. package/content-config.mjs +333 -210
  10. package/deploy.mjs +116 -10
  11. package/docs/api.md +238 -246
  12. package/docs/authoring/assets.md +11 -5
  13. package/docs/authoring/frontmatter.md +1 -1
  14. package/docs/authoring/links-and-markup.md +87 -0
  15. package/docs/commands.md +138 -99
  16. package/docs/configuration.md +277 -125
  17. package/docs/content-format.md +2 -0
  18. package/docs/diagnostics.md +48 -13
  19. package/docs/guides/book.md +341 -21
  20. package/docs/guides/e2e.md +13 -2
  21. package/docs/guides/icons.md +14 -4
  22. package/docs/guides/module-project.md +18 -8
  23. package/docs/guides/release-and-deploy.md +54 -6
  24. package/docs/guides/site.md +5 -2
  25. package/docs/project-setup.md +30 -10
  26. package/docs/reference/format-details.md +373 -170
  27. package/docs/reference/note-types.md +128 -109
  28. package/docs/reference/theme-pages.md +31 -6
  29. package/e2e.mjs +140 -28
  30. package/engine/actor-compiler.mjs +22 -31
  31. package/engine/address-charset.mjs +4 -17
  32. package/engine/address-fields.mjs +1 -1
  33. package/engine/address-render.mjs +12 -1
  34. package/engine/address-values.mjs +6 -0
  35. package/engine/address.mjs +46 -33
  36. package/engine/art-fields.mjs +30 -5
  37. package/engine/art-slots.mjs +10 -1
  38. package/engine/asset-bindings.mjs +12 -1
  39. package/engine/base-compiler.mjs +34 -65
  40. package/engine/being-age.mjs +2 -7
  41. package/engine/being-measurements.mjs +12 -1
  42. package/engine/calendar-artifacts.mjs +6 -0
  43. package/engine/calendar-choice.mjs +12 -1
  44. package/engine/calendar-format.mjs +12 -1
  45. package/engine/calendar-human.mjs +12 -1
  46. package/engine/compile-corpus.mjs +3 -1
  47. package/engine/content-address.mjs +9 -12
  48. package/engine/content-alerts.mjs +13 -1
  49. package/engine/content-blocks.mjs +14 -3
  50. package/engine/content-embeds.mjs +11 -3
  51. package/engine/content-figures.mjs +9 -0
  52. package/engine/content-footnotes.mjs +12 -1
  53. package/engine/content-format-check.mjs +11 -262
  54. package/engine/content-format.yaml +5 -2
  55. package/engine/content-images.mjs +3 -0
  56. package/engine/content-index.mjs +443 -20
  57. package/engine/content-links.mjs +29 -35
  58. package/engine/content-lint.mjs +2 -3
  59. package/engine/content-poetry.mjs +12 -1
  60. package/engine/content-slug.mjs +2 -14
  61. package/engine/content-spans.mjs +13 -1
  62. package/engine/content-tables.mjs +12 -1
  63. package/engine/culture-choice.mjs +210 -13
  64. package/engine/data-keys.mjs +19 -16
  65. package/engine/date-conversion.mjs +12 -1
  66. package/engine/declaration-check.mjs +9 -0
  67. package/engine/derived-fields.mjs +6 -7
  68. package/engine/diagnostics.mjs +34 -4
  69. package/engine/docs-checks.mjs +9 -0
  70. package/engine/document-subtypes.mjs +47 -34
  71. package/engine/event-views.mjs +139 -14
  72. package/engine/exported-scene.mjs +92 -28
  73. package/engine/extension-attributes.mjs +12 -1
  74. package/engine/field-spec.mjs +11 -102
  75. package/engine/folder-notes.mjs +0 -64
  76. package/engine/foreign-catalog.mjs +2 -1
  77. package/engine/format-generated.mjs +9 -0
  78. package/engine/foundry-entries.mjs +10 -28
  79. package/engine/frontmatter-lint.mjs +83 -392
  80. package/engine/frontmatter.mjs +20 -70
  81. package/engine/generate.mjs +10 -15
  82. package/engine/heading-attributes.mjs +12 -1
  83. package/engine/helpers.mjs +41 -102
  84. package/engine/holdings.mjs +1 -1
  85. package/engine/homepage.mjs +3 -10
  86. package/engine/ids.mjs +1 -167
  87. package/engine/index-records.mjs +6 -4
  88. package/engine/index.mjs +0 -3
  89. package/engine/infobox-render.mjs +15 -3
  90. package/engine/infobox.mjs +13 -14
  91. package/engine/item-compiler.mjs +4 -10
  92. package/engine/item-docs.mjs +3 -5
  93. package/engine/item-registry.mjs +2 -10
  94. package/engine/journals.mjs +1 -5
  95. package/engine/literature-notes.mjs +4 -12
  96. package/engine/macros.mjs +1 -2
  97. package/engine/map-graphviz.mjs +12 -1
  98. package/engine/markdown-expressions.mjs +12 -1
  99. package/engine/markdownlint-run.mjs +567 -0
  100. package/engine/metadata-index.mjs +42 -12
  101. package/engine/note-addresses.mjs +143 -35
  102. package/engine/note-claims.mjs +14 -28
  103. package/engine/note-dates.mjs +3 -3
  104. package/engine/note-frontmatter.mjs +6 -0
  105. package/engine/note-ids.mjs +8 -14
  106. package/engine/note-package.mjs +8 -25
  107. package/engine/note-state.mjs +1 -3
  108. package/engine/note-vocabulary.mjs +148 -84
  109. package/engine/number-words.mjs +12 -1
  110. package/engine/pack-config.mjs +15 -25
  111. package/engine/pack-router.mjs +10 -16
  112. package/engine/pathnames.mjs +8 -22
  113. package/engine/pdf-build.mjs +773 -121
  114. package/engine/pdf-coverage.mjs +188 -0
  115. package/engine/pdf-index.mjs +54 -7
  116. package/engine/pdf-pages.mjs +247 -0
  117. package/engine/pdf-render.mjs +114 -4
  118. package/engine/pdf-toc.mjs +29 -32
  119. package/engine/project-init.mjs +46 -6
  120. package/engine/prose-config.mjs +1 -1
  121. package/engine/prose-lint.mjs +52 -88
  122. package/engine/readability-lint.mjs +9 -0
  123. package/engine/reckoning-markers.mjs +12 -1
  124. package/engine/reference-targets.mjs +7 -0
  125. package/engine/runtime-only-fields.mjs +5 -8
  126. package/engine/scene-levels.mjs +2 -2
  127. package/engine/scenes.mjs +1 -1
  128. package/engine/shortcode-references.mjs +7 -0
  129. package/engine/site-build.mjs +30 -16
  130. package/engine/site-index.mjs +10 -16
  131. package/engine/site-preview.mjs +6 -0
  132. package/engine/site-root.mjs +8 -1
  133. package/engine/social-tie-terms.mjs +12 -1
  134. package/engine/social-ties.mjs +3 -0
  135. package/engine/sql-tables.mjs +56 -20
  136. package/engine/standing-terms.mjs +11 -1
  137. package/engine/standings.mjs +11 -27
  138. package/engine/system-block.mjs +39 -141
  139. package/engine/system-vocabulary.mjs +6 -0
  140. package/engine/walk-files.mjs +69 -0
  141. package/engine/web-wikilinks.mjs +23 -3
  142. package/engine/wikilink-syntax.mjs +32 -21
  143. package/engine/wikilinks.mjs +27 -16
  144. package/engine/yaml-lint.mjs +7 -4
  145. package/githooks/attribution.mjs +8 -0
  146. package/githooks/commit-message.mjs +9 -0
  147. package/hm3/actors.mjs +9 -48
  148. package/hm3/default-item-art.mjs +9 -9
  149. package/hm3/item-fields.mjs +2 -9
  150. package/hm3/template-priority.mjs +6 -7
  151. package/hugo-theme/data/banner-kinds.yaml +78 -0
  152. package/hugo-theme/data/banners.yaml +2 -3
  153. package/hugo-theme/layouts/404.html +3 -3
  154. package/hugo-theme/layouts/partials/banner-url.html +31 -7
  155. package/hugo-theme/layouts/partials/hero-banner.html +13 -14
  156. package/hugo-theme/layouts/partials/related.html +1 -1
  157. package/hugo-theme/layouts/partials/warn-missing-banner.html +1 -1
  158. package/hugo-theme/static/css/style.css +1 -1
  159. package/manifest.mjs +11 -4
  160. package/markdownlint-config.mjs +1 -1
  161. package/package.json +6 -3
  162. package/release.mjs +83 -18
  163. package/sohl/actors.mjs +16 -27
  164. package/sohl/default-item-art.mjs +3 -3
  165. package/sohl/document-subtypes.mjs +1 -16
  166. package/sohl/infobox.mjs +2 -3
  167. package/sohl/item-builders.mjs +5 -8
  168. package/sohl/item-fields.mjs +5 -35
  169. package/sohl/items.mjs +0 -4
  170. package/sohl/kb-passes.mjs +3 -3
  171. package/types/container.d.mts +116 -5
  172. package/types/content-config.d.mts +83 -35
  173. package/types/deploy.d.mts +42 -6
  174. package/types/e2e.d.mts +35 -3
  175. package/types/engine/address-charset.d.mts +4 -17
  176. package/types/engine/address.d.mts +17 -8
  177. package/types/engine/art-fields.d.mts +7 -4
  178. package/types/engine/art-slots.d.mts +6 -0
  179. package/types/engine/base-compiler.d.mts +15 -17
  180. package/types/engine/content-address.d.mts +9 -12
  181. package/types/engine/content-embeds.d.mts +4 -2
  182. package/types/engine/content-format-check.d.mts +0 -64
  183. package/types/engine/content-index.d.mts +82 -3
  184. package/types/engine/content-links.d.mts +2 -4
  185. package/types/engine/culture-choice.d.mts +51 -8
  186. package/types/engine/data-keys.d.mts +2 -2
  187. package/types/engine/derived-fields.d.mts +1 -2
  188. package/types/engine/diagnostics.d.mts +27 -4
  189. package/types/engine/document-subtypes.d.mts +12 -31
  190. package/types/engine/event-views.d.mts +14 -2
  191. package/types/engine/exported-scene.d.mts +3 -2
  192. package/types/engine/field-spec.d.mts +13 -122
  193. package/types/engine/folder-notes.d.mts +0 -39
  194. package/types/engine/foreign-catalog.d.mts +2 -1
  195. package/types/engine/foundry-entries.d.mts +4 -5
  196. package/types/engine/frontmatter-lint.d.mts +2 -2
  197. package/types/engine/frontmatter.d.mts +19 -45
  198. package/types/engine/generate.d.mts +1 -1
  199. package/types/engine/helpers.d.mts +25 -42
  200. package/types/engine/homepage.d.mts +3 -10
  201. package/types/engine/ids.d.mts +0 -114
  202. package/types/engine/index-records.d.mts +6 -4
  203. package/types/engine/index.d.mts +0 -1
  204. package/types/engine/infobox-render.d.mts +7 -1
  205. package/types/engine/infobox.d.mts +3 -2
  206. package/types/engine/item-docs.d.mts +1 -1
  207. package/types/engine/item-registry.d.mts +2 -4
  208. package/types/engine/literature-notes.d.mts +1 -1
  209. package/types/engine/markdownlint-run.d.mts +40 -0
  210. package/types/engine/metadata-index.d.mts +9 -1
  211. package/types/engine/note-addresses.d.mts +27 -2
  212. package/types/engine/note-claims.d.mts +3 -5
  213. package/types/engine/note-ids.d.mts +2 -4
  214. package/types/engine/note-package.d.mts +1 -1
  215. package/types/engine/note-state.d.mts +1 -3
  216. package/types/engine/note-vocabulary.d.mts +28 -21
  217. package/types/engine/pack-config.d.mts +2 -6
  218. package/types/engine/pack-router.d.mts +4 -4
  219. package/types/engine/pathnames.d.mts +3 -3
  220. package/types/engine/pdf-build.d.mts +98 -12
  221. package/types/engine/pdf-coverage.d.mts +60 -0
  222. package/types/engine/pdf-index.d.mts +34 -5
  223. package/types/engine/pdf-pages.d.mts +143 -0
  224. package/types/engine/pdf-render.d.mts +45 -1
  225. package/types/engine/pdf-toc.d.mts +12 -14
  226. package/types/engine/prose-config.d.mts +1 -1
  227. package/types/engine/prose-lint.d.mts +11 -10
  228. package/types/engine/runtime-only-fields.d.mts +2 -2
  229. package/types/engine/site-build.d.mts +9 -5
  230. package/types/engine/site-index.d.mts +4 -5
  231. package/types/engine/site-root.d.mts +1 -1
  232. package/types/engine/sql-tables.d.mts +31 -2
  233. package/types/engine/standing-terms.d.mts +2 -1
  234. package/types/engine/standings.d.mts +7 -9
  235. package/types/engine/system-block.d.mts +10 -44
  236. package/types/engine/walk-files.d.mts +15 -0
  237. package/types/engine/wikilink-syntax.d.mts +18 -19
  238. package/types/engine/yaml-lint.d.mts +5 -4
  239. package/types/hm3/actors.d.mts +1 -2
  240. package/types/hm3/item-fields.d.mts +2 -4
  241. package/types/hm3/template-priority.d.mts +6 -7
  242. package/types/manifest.d.mts +3 -2
  243. package/types/release.d.mts +12 -7
  244. package/types/sohl/actors.d.mts +2 -1
  245. package/types/sohl/document-subtypes.d.mts +1 -2
  246. package/types/sohl/item-fields.d.mts +3 -7
  247. package/engine/retired-fields.mjs +0 -631
  248. package/types/engine/retired-fields.d.mts +0 -354
package/docs/reference/note-types.md CHANGED
@@ -30,16 +30,15 @@ These are the only keys a note writes at its top level, in the order the formatt
30
30
 
31
31
  ## Shared `data` fields
32
32
 
33
- These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can.
33
+ These fields are accepted by every note type. A field's value can still be irrelevant to a particular output; the build reports that where it can. `data.icon` is not shared: it is listed under each type whose document carries art.
34
34
 
35
- | Field | Shape | Meaning |
36
- | ----------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------ |
37
- | `data.id` | string | A fixed document identity when the derived identity is unsuitable. |
38
- | `data.pack` | string | The shared compendium route, with a system block overriding it. |
39
- | `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it. |
40
- | `data.harnworld` | `{ realm?, ritual? }` | HârnWorld source details shared by every system — `realm` and `ritual`. |
41
- | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
42
- | `data.banner` | an Address | The page's hero image — an `image` address, cut to 1792×768. Reaches no compiled document. |
35
+ | Field | Shape | Meaning |
36
+ | ----------------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
37
+ | `data.id` | string | A fixed document identity when the derived identity is unsuitable. |
38
+ | `data.pack` | string | The shared compendium route, with a system block overriding it. |
39
+ | `data.packFolder` | an Address, or a map of Addresses keyed by pack | The shared compendium folder Address, with a system block overriding it. |
40
+ | `data.harnworld` | `{ realm?, ritual? }` | HârnWorld source details shared by every system — `realm` and `ritual`. |
41
+ | `data.banner` | an Address | The page's hero image — an `image` address, cut to 1792×768, or `none` to decline a hero image. Reaches no compiled document. |
43
42
 
44
43
  **Inner keys** — a key a field's value does not declare is an error at its own line and column.
45
44
 
@@ -54,40 +53,41 @@ These fields are accepted by every note type. A field's value can still be irrel
54
53
 
55
54
  **Subtypes:** `npc`, `character`, `creature`.
56
55
 
57
- | Field | Shape | Meaning |
58
- | -------------------------------- | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
59
- | `data.tokenIcon` | an Address | What a token on the canvas wears — an `icon` address; unset, it follows `icon`. |
60
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
61
- | `data.archetypes` | list of strings | Archetypal behaviours the being fits. |
62
- | `data.occupation` | string | What the being does for a living. |
63
- | `data.stations` | list of Addresses | Stations the being holds. |
64
- | `data.lore` | list of Addresses | Lore concerning this being — the law it lives under, the customs it is subject to, the traditions it was raised in. |
65
- | `data.culture` | an Address | The being's primary culture, as a culture lore note. |
66
- | `data.homes` | list of Addresses | Places the being calls home. |
67
- | `data.affiliations` | a standing map keyed by Address, or a list of Addresses | Bodies the being belongs to, keyed by Address, each entry holding the standing it holds there — `rank`, required, a level on that body's own ladder, and `office`, optional, a post that body names. |
68
- | `data.socialTies` | a map keyed by Address | Defining ties directed from this being to others: `patron` (Supports the subject from greater power, wealth, or status.); `friend` (Supports the subject out of goodwill.); `dependent` (Relies on the subject's support or protection.); `acquaintance` (Knows the subject without a strong disposition.); `rival` (Opposes the subject without implacable hostility.); `nemesis` (Opposes the subject personally and implacably.) |
69
- | `data.gender` | string | One of `male`, `female`, `nonbinary`, `none` or `other`. `none` says the being has no gender; an absent field says its gender is unrecorded. |
70
- | `data.species` | an Address | The being's species, as a lore note. |
71
- | `data.born` | string | When the being was born — a date, or `unknown` where the birth is unrecorded. Absent, the being was never born. |
72
- | `data.calendar` | an Address | Calendar used to display this being's dates. |
73
- | `data.died` | string | When the being died — a date, or `unknown` where the death is unrecorded. Absent, the being is alive. |
74
- | `data.age` | string | Age in years, stated only to override what `born` says — `34`, or `~34` for an estimate. Unstated beside a dated `born` it is computed; unstated beside an unknown or absent `born` the age is unknown. |
75
- | `data.ageYears` | number | Written by the compiler beside an `age` estimate — the `~` stripped, the magnitude alone. A note never authors this. |
76
- | `data.height` | metres or feet and inches | Height in metres or feet and inches. |
77
- | `data.weight` | kilograms or pounds | Body weight in kilograms or pounds. |
78
- | `data.frame` | string | Relative frame — one of `scant`, `light`, `medium`, `heavy` or `massive`. |
79
- | `data.appearance.eye_color` | string | Eye colour. |
80
- | `data.appearance.hair_color` | string | Hair colour. |
81
- | `data.appearance.skin_color` | string | Skin colour. |
82
- | `data.appearance.complexion` | string or list | The skin's condition — one value, or several, because a face carries more than one at once. A single value means a list of one. |
83
- | `data.appearance.extra_features` | list of strings | Anything else a stranger would notice. |
56
+ | Field | Shape | Meaning |
57
+ | -------------------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
59
+ | `data.tokenIcon` | an Address | What a token on the canvas wears — an `icon` address; unset, it follows `icon`. |
60
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
61
+ | `data.archetypes` | list of strings | Archetypal behaviours the being fits. |
62
+ | `data.occupation` | string | What the being does for a living. |
63
+ | `data.lore` | list of Addresses | Lore concerning this being — the law it lives under, the customs it is subject to, the traditions it was raised in. |
64
+ | `data.culture` | an Address | The being's primary culture, as a culture lore note. |
65
+ | `data.homes` | list of Addresses | Places the being calls home. |
66
+ | `data.affiliations` | a standing map keyed by Address | Bodies the being belongs to, keyed by Address, each entry holding the standing it holds there — `rank`, required, a level on that body's own ladder, and `office`, optional, a post that body names. |
67
+ | `data.socialTies` | a map keyed by Address | Defining ties directed from this being to others: `patron` (Supports the subject from greater power, wealth, or status.); `friend` (Supports the subject out of goodwill.); `dependent` (Relies on the subject's support or protection.); `acquaintance` (Knows the subject without a strong disposition.); `rival` (Opposes the subject without implacable hostility.); `nemesis` (Opposes the subject personally and implacably.) |
68
+ | `data.gender` | string | One of `male`, `female`, `nonbinary`, `none` or `other`. `none` says the being has no gender; an absent field says its gender is unrecorded. |
69
+ | `data.species` | an Address | The being's species, as a lore note. |
70
+ | `data.born` | string | When the being was born — a date, or `unknown` where the birth is unrecorded. Absent, the being was never born. |
71
+ | `data.calendar` | an Address | Calendar that displays this being's dates. |
72
+ | `data.died` | string | When the being died — a date, or `unknown` where the death is unrecorded. Absent, the being is alive. |
73
+ | `data.age` | string | Age in years, stated only to override what `born` says — `34`, or `~34` for an estimate. Unstated beside a dated `born` it is computed; unstated beside an unknown or absent `born` the age is unknown. |
74
+ | `data.ageYears` | number | Written by the compiler beside an `age` estimate — the `~` stripped, the magnitude alone. A note never authors this. |
75
+ | `data.height` | metres or feet and inches | Height in metres or feet and inches. |
76
+ | `data.weight` | kilograms or pounds | Body weight in kilograms or pounds. |
77
+ | `data.frame` | string | Relative frame — one of `scant`, `light`, `medium`, `heavy` or `massive`. |
78
+ | `data.appearance.eye_color` | string | Eye colour. |
79
+ | `data.appearance.hair_color` | string | Hair colour. |
80
+ | `data.appearance.skin_color` | string | Skin colour. |
81
+ | `data.appearance.complexion` | string or list | The skin's condition — one value, or several, because a face carries more than one at once. A single value means a list of one. |
82
+ | `data.appearance.extra_features` | list of strings | Anything else a stranger would notice. |
84
83
 
85
84
  **Inner keys** — a key a field's value does not declare is an error at its own line and column.
86
85
 
87
- | Key | Shape | Required | Meaning |
88
- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
89
- | `data.affiliations.<Address>.rank` | the level on that body's own ladder, as a whole number — an ordinary member is `1`, and `0` is the rung for someone cast out | yes | The level on the body's own `governance.ranks` ladder. |
90
- | `data.affiliations.<Address>.office` | a post from that body's `governance.offices` | no | A post the body names in its `governance.offices`, where one is held. |
86
+ | Key | Shape | Required | Meaning |
87
+ | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
88
+ | `data.affiliations.<Address>.rank` | the level on that body's own ladder, as a whole number — an ordinary member is `1`, and `0` is the rung for someone cast out | yes | The level on the body's own `governance.ranks` ladder. |
89
+ | `data.affiliations.<Address>.office` | a post from that body's `governance.offices` | no | A post the body names in its `governance.offices`, where one is held. |
90
+ | `data.affiliations.<Address>.societies` | a list of society names | no | The societies the membership is held in, by name. SoHL carries one, the first, as the affiliation item's `system.society`. |
91
91
 
92
92
  **System mappings**
93
93
 
@@ -110,6 +110,7 @@ These fields are accepted by every note type. A field's value can still be irrel
110
110
 
111
111
  | Field | Shape | Meaning |
112
112
  | ----------------------- | ---------- | ------------------------------------------------------------------------------- |
113
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
113
114
  | `data.tokenIcon` | an Address | What a token on the canvas wears — an `icon` address; unset, it follows `icon`. |
114
115
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
115
116
 
@@ -119,6 +120,7 @@ These fields are accepted by every note type. A field's value can still be irrel
119
120
 
120
121
  | Field | Shape | Meaning |
121
122
  | ------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
123
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
122
124
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
123
125
  | `data.events` | list of event entries | What happened to or at this subject — each entry one dated, attributed event: a founding, a war, a fall, or an occasion that recurs. |
124
126
  | `data.demonym` | string | What one member is called — a Vylarian. |
@@ -133,6 +135,7 @@ These fields are accepted by every note type. A field's value can still be irrel
133
135
  | `data.economy` | list of Addresses | What its economic life runs on — currencies, banking bodies, goods. |
134
136
  | `data.lore` | list of Addresses | Lore concerning it — the peoples it draws on, the god a faith venerates, its law, its calendar. |
135
137
  | `data.parents` | list of Addresses | Affiliations it is subordinate to. |
138
+ | `data.culture` | an Address | The people this affiliation belongs to, as a culture lore note. |
136
139
  | `data.relations` | a map keyed by Address | Standing with other affiliations — aligned, unaligned, rival, nemesis. |
137
140
 
138
141
  **Inner keys** — a key a field's value does not declare is an error at its own line and column.
@@ -201,20 +204,21 @@ These fields are accepted by every note type. A field's value can still be irrel
201
204
 
202
205
  **Subtypes:** `disease`, `poisontoxin`, `maladiction`.
203
206
 
204
- | Field | Shape | Meaning |
205
- | ---------------------------------- | ------ | -------------------------------------------------------------- |
206
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
207
- | `data.transmission` | string | How it passes from one host to another. |
208
- | `data.outcome` | string | Where it ends once it has run its course — `death` or `cured`. |
209
- | `data.healingRate` | number | How readily a healing test goes well. |
210
- | `data.contagionIndex` | number | How contagious it is. |
211
- | `data.outcomeTraumas` | string | Expression returning the traumas recovery leaves behind. |
212
- | `data.onsetDurationFormula` | string | Roll formula for the delay between contraction and onset. |
213
- | `data.onsetDurationBase` | number | That delay in seconds, stated outright instead of rolled. |
214
- | `data.healingCheckDurationFormula` | string | Roll formula for the interval between healing checks. |
215
- | `data.healingCheckDurationBase` | number | That interval in seconds, stated outright instead of rolled. |
216
- | `data.resolutionDurationFormula` | string | Roll formula for the time from onset to resolution. |
217
- | `data.resolutionDurationBase` | number | That time in seconds, stated outright instead of rolled. |
207
+ | Field | Shape | Meaning |
208
+ | ---------------------------------- | ---------- | -------------------------------------------------------------------- |
209
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
210
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
211
+ | `data.transmission` | string | How it passes from one host to another. |
212
+ | `data.outcome` | string | Where it ends once it has run its course — `death` or `cured`. |
213
+ | `data.healingRate` | number | How readily a healing test goes well. |
214
+ | `data.contagionIndex` | number | How contagious it is. |
215
+ | `data.outcomeTraumas` | string | Expression returning the traumas recovery leaves behind. |
216
+ | `data.onsetDurationFormula` | string | Roll formula for the delay between contraction and onset. |
217
+ | `data.onsetDurationBase` | number | That delay in seconds, stated outright instead of rolled. |
218
+ | `data.healingCheckDurationFormula` | string | Roll formula for the interval between healing checks. |
219
+ | `data.healingCheckDurationBase` | number | That interval in seconds, stated outright instead of rolled. |
220
+ | `data.resolutionDurationFormula` | string | Roll formula for the time from onset to resolution. |
221
+ | `data.resolutionDurationBase` | number | That time in seconds, stated outright instead of rolled. |
218
222
 
219
223
  **System mappings**
220
224
 
@@ -237,6 +241,7 @@ These fields are accepted by every note type. A field's value can still be irrel
237
241
 
238
242
  | Field | Shape | Meaning |
239
243
  | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
244
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
240
245
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
241
246
  | `data.weight` | number | What the thing weighs. |
242
247
  | `data.value` | number | What the thing is worth. |
@@ -260,17 +265,19 @@ These fields are accepted by every note type. A field's value can still be irrel
260
265
 
261
266
  **Subtypes:** Open vocabulary.
262
267
 
263
- | Field | Shape | Meaning |
264
- | ----------------------- | ------ | ---------------------------------------------------------- |
265
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
268
+ | Field | Shape | Meaning |
269
+ | ----------------------- | ---------- | -------------------------------------------------------------------- |
270
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
271
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
266
272
 
267
273
  ### attribute
268
274
 
269
275
  **Subtypes:** None.
270
276
 
271
- | Field | Shape | Meaning |
272
- | ----------------------- | ------ | ---------------------------------------------------------- |
273
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
277
+ | Field | Shape | Meaning |
278
+ | ----------------------- | ---------- | -------------------------------------------------------------------- |
279
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
280
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
274
281
 
275
282
  ### concoctiongear
276
283
 
@@ -278,6 +285,7 @@ These fields are accepted by every note type. A field's value can still be irrel
278
285
 
279
286
  | Field | Shape | Meaning |
280
287
  | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
288
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
281
289
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
282
290
  | `data.weight` | number | What the thing weighs. |
283
291
  | `data.value` | number | What the thing is worth. |
@@ -305,6 +313,7 @@ These fields are accepted by every note type. A field's value can still be irrel
305
313
 
306
314
  | Field | Shape | Meaning |
307
315
  | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
316
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
308
317
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
309
318
  | `data.weight` | number | What the thing weighs. |
310
319
  | `data.value` | number | What the thing is worth. |
@@ -332,6 +341,7 @@ These fields are accepted by every note type. A field's value can still be irrel
332
341
 
333
342
  | Field | Shape | Meaning |
334
343
  | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
344
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
335
345
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
336
346
  | `data.weight` | number | What the thing weighs. |
337
347
  | `data.value` | number | What the thing is worth. |
@@ -359,6 +369,7 @@ These fields are accepted by every note type. A field's value can still be irrel
359
369
 
360
370
  | Field | Shape | Meaning |
361
371
  | ----------------------- | -------------------------------------------- | -------------------------------------------------------------------------- |
372
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
362
373
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
363
374
  | `data.assocSkill` | an Address | The skill it is associated with. |
364
375
  | `data.assocAffiliation` | an Address | The affiliation it is associated with. |
@@ -380,15 +391,16 @@ These fields are accepted by every note type. A field's value can still be irrel
380
391
 
381
392
  **Subtypes:** `spiritrite`, `spiritaction`, `spiritpower`, `ritualaction`, `divineincantation`, `arcaneincantation`, `arcanetalent`, `spirittalent`, `alchemy`, `divination`.
382
393
 
383
- | Field | Shape | Meaning |
384
- | ----------------------- | ---------- | ---------------------------------------------------------- |
385
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
386
- | `data.assocSkill` | an Address | The skill it is associated with. |
387
- | `data.assocAffiliation` | an Address | The affiliation it is associated with. |
388
- | `data.masteryLevel` | number | Mastery before any modifier. |
389
- | `data.level` | number | The magnitude of the ability. |
390
- | `data.charges.value` | number | Charges available now; unset means charges are not used. |
391
- | `data.charges.max` | number | Most charges it can hold; unset means no maximum. |
394
+ | Field | Shape | Meaning |
395
+ | ----------------------- | ---------- | -------------------------------------------------------------------- |
396
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
397
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
398
+ | `data.assocSkill` | an Address | The skill it is associated with. |
399
+ | `data.assocAffiliation` | an Address | The affiliation it is associated with. |
400
+ | `data.masteryLevel` | number | Mastery before any modifier. |
401
+ | `data.level` | number | The magnitude of the ability. |
402
+ | `data.charges.value` | number | Charges available now; unset means charges are not used. |
403
+ | `data.charges.max` | number | Most charges it can hold; unset means no maximum. |
392
404
 
393
405
  **System mappings**
394
406
 
@@ -404,6 +416,7 @@ These fields are accepted by every note type. A field's value can still be irrel
404
416
 
405
417
  | Field | Shape | Meaning |
406
418
  | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
419
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
407
420
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
408
421
  | `data.weight` | number | What the thing weighs. |
409
422
  | `data.value` | number | What the thing is worth. |
@@ -430,11 +443,12 @@ These fields are accepted by every note type. A field's value can still be irrel
430
443
 
431
444
  **Subtypes:** `social`, `nature`, `craft`, `lore`, `language`, `script`, `mystical`, `physical`, `combat`, `combattechnique`.
432
445
 
433
- | Field | Shape | Meaning |
434
- | ----------------------- | ---------- | ---------------------------------------------------------- |
435
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
436
- | `data.masteryLevel` | number | Mastery before any modifier. |
437
- | `data.parentSkill` | an Address | The skill this one specialises. |
446
+ | Field | Shape | Meaning |
447
+ | ----------------------- | ---------- | -------------------------------------------------------------------- |
448
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
449
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
450
+ | `data.masteryLevel` | number | Mastery before any modifier. |
451
+ | `data.parentSkill` | an Address | The skill this one specialises. |
438
452
 
439
453
  **System mappings**
440
454
 
@@ -447,15 +461,16 @@ These fields are accepted by every note type. A field's value can still be irrel
447
461
 
448
462
  **Subtypes:** `injury`, `fear`, `morale`, `pall`, `psycond`, `physcond`, `auralshock`, `fatigue`, `infection`, `shock`, `coma`.
449
463
 
450
- | Field | Shape | Meaning |
451
- | -------------------------------------- | ------ | ------------------------------------------------------------------- |
452
- | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
453
- | `data.healingCheckDurationFormula` | string | Roll formula for the interval between healing checks. |
454
- | `data.healingCheckDurationBase` | number | That interval in seconds, stated outright instead of rolled. |
455
- | `data.bloodLossAdvanceDurationFormula` | string | Roll formula for the interval between blood-loss advances. |
456
- | `data.bloodLossAdvanceDurationBase` | number | That interval in seconds. Setting it is what makes the wound bleed. |
457
- | `data.courseDurationFormula` | string | Roll formula for the interval between course tests. |
458
- | `data.courseDurationBase` | number | That interval in seconds, stated outright instead of rolled. |
464
+ | Field | Shape | Meaning |
465
+ | -------------------------------------- | ---------- | -------------------------------------------------------------------- |
466
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
467
+ | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
468
+ | `data.healingCheckDurationFormula` | string | Roll formula for the interval between healing checks. |
469
+ | `data.healingCheckDurationBase` | number | That interval in seconds, stated outright instead of rolled. |
470
+ | `data.bloodLossAdvanceDurationFormula` | string | Roll formula for the interval between blood-loss advances. |
471
+ | `data.bloodLossAdvanceDurationBase` | number | That interval in seconds. Setting it is what makes the wound bleed. |
472
+ | `data.courseDurationFormula` | string | Roll formula for the interval between course tests. |
473
+ | `data.courseDurationBase` | number | That interval in seconds, stated outright instead of rolled. |
459
474
 
460
475
  **System mappings**
461
476
 
@@ -475,6 +490,7 @@ These fields are accepted by every note type. A field's value can still be irrel
475
490
 
476
491
  | Field | Shape | Meaning |
477
492
  | ----------------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
493
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
478
494
  | `data.templatePriority` | number | Template priority; unset means the note is not a template. |
479
495
  | `data.weight` | number | What the thing weighs. |
480
496
  | `data.value` | number | What the thing is worth. |
@@ -500,20 +516,20 @@ These fields are accepted by every note type. A field's value can still be irrel
500
516
 
501
517
  Lore records in-world knowledge. A `culture` describes a people; a `custom` describes how they practice a rite, observance, or usage. A `material` describes a physical constituent and its qualities, which may vary by region. See the [lore subtype definitions](format-details.md#type-lore) for the complete vocabulary.
502
518
 
503
- | Field | Shape | Meaning |
504
- | ---------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
505
- | `data.epoch` | a canonical `<year>.<day>` | Canonical day when calendar year 1, day 1 begins — `1.1`. |
506
- | `data.months` | list of `{ name, abbreviation?, days }` | The months this calendar keeps, in order — position in the list is position in the year, and the day counts sum to the world's year. |
507
- | `data.weekdays` | list of `{ name, abbreviation? }` | The days of the week this calendar names, in order. A calendar with no week writes none. |
508
- | `data.seasons` | list of `{ name, abbreviation?, start }` | The seasons this calendar marks, starting on numbered days of the year. |
509
- | `data.namedDays` | list of `{ name, abbreviation?, day }` | Names assigned to particular days of the year. |
510
- | `data.eras` | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months. |
511
- | `data.formats` | map of named Calendaria format strings | Named patterns for reading and writing this calendar's dates. |
512
- | `data.culture` | an Address | The people whose work this is, as a culture lore note. |
513
- | `data.form` | string | The kind of work in its people's own terms — an epic, a saga, a praise-song, an elegy. Free text. |
514
- | `data.subjects` | list of Addresses | The beings, places, gods and other notes the work concerns, and each event it concerns, named as `place-ironfells#sack`. |
515
- | `data.language` | an Address | The tongue the work is composed in, as a language skill note. |
516
- | `data.events` | list of event entries | What happened to or at this subject — each entry one dated, attributed event: a founding, a war, a fall, or an occasion that recurs. |
519
+ | Field | Shape | Meaning |
520
+ | ---------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
521
+ | `data.epoch` | a canonical `<year>.<day>` | Canonical day when calendar year 1, day 1 begins — `1.1`. |
522
+ | `data.months` | list of `{ name, abbreviation?, days }` | The months this calendar keeps, in order — position in the list is position in the year, and the day counts sum to the world's year. |
523
+ | `data.weekdays` | list of `{ name, abbreviation? }` | The days of the week this calendar names, in order. A calendar with no week writes none. |
524
+ | `data.seasons` | list of `{ name, abbreviation?, start }` | The seasons this calendar marks, starting on numbered days of the year. |
525
+ | `data.namedDays` | list of `{ name, abbreviation?, day }` | Names assigned to particular days of the year. |
526
+ | `data.eras` | list of `{ shortcode, name, marker?, abbreviation?, proclaimedBy?, start, label? }` | The year-counts kept in this calendar. A marker names one era and uses these months. |
527
+ | `data.formats` | map of named Calendaria format strings | Named patterns for reading and writing this calendar's dates. |
528
+ | `data.culture` | an Address | The people this lore belongs to — for a work of literature, the people whose work it is — as a culture lore note. A culture note is its own culture, and states the field only as itself. |
529
+ | `data.form` | string | The kind of work in its people's own terms — an epic, a saga, a praise-song, an elegy. Free text. |
530
+ | `data.subjects` | list of Addresses | The beings, places, gods and other notes the work concerns, and each event it concerns, named as `place-ironfells#sack`. |
531
+ | `data.language` | an Address | The tongue the work is composed in, as a language skill note. |
532
+ | `data.events` | list of event entries | What happened to or at this subject — each entry one dated, attributed event: a founding, a war, a fall, or an occasion that recurs. |
517
533
 
518
534
  **Inner keys** — a key a field's value does not declare is an error at its own line and column.
519
535
 
@@ -582,11 +598,12 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
582
598
 
583
599
  **Subtypes:** `battlemap`, `localmap`, `regionalmap`, `totm`.
584
600
 
585
- | Field | Shape | Meaning |
586
- | ------------ | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
587
- | `data.scene` | an object — a Foundry Scene document as exported | The Foundry Scene as exported, passed through unchanged apart from `data.fixup` and its pins marked `#anchor`. Nothing inside it is checked; the book prints its levels' background images. |
588
- | `data.fixup` | list of `{ path, type, value }` | Asset address replacements in an exported Scene. |
589
- | `data.place` | an Address | The place this map depicts. Named here and not on the place, because a place has several maps and a map depicts one place. |
601
+ | Field | Shape | Meaning |
602
+ | ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
603
+ | `data.scene` | an object — a Foundry Scene document as exported | The Foundry Scene as exported, passed through unchanged apart from `data.fixup` and its pins marked `#anchor`. Nothing inside it is checked; the book prints its levels' background images. |
604
+ | `data.fixup` | list of `{ path, type, value }` | Asset address replacements in an exported Scene. |
605
+ | `data.thumbnail` | an Address | The map's thumbnail — an `image` address, resolved into the Scene's `thumb` the way a `data.fixup` entry is. Background art is untouched. |
606
+ | `data.place` | an Address | The place this map depicts. Named here and not on the place, because a place has several maps and a map depicts one place. |
590
607
 
591
608
  **Inner keys** — a key a field's value does not declare is an error at its own line and column.
592
609
 
@@ -603,11 +620,12 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
603
620
  | Field | Shape | Meaning |
604
621
  | -------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
605
622
  | `data.events` | list of event entries | What happened to or at this subject — each entry one dated, attributed event: a founding, a war, a fall, or an occasion that recurs. |
606
- | `data.calendar` | an Address | Calendar used to display this place's dates. |
623
+ | `data.calendar` | an Address | Calendar that displays this place's dates. |
607
624
  | `data.demonym` | string | What a person from this place is called — a Vylarian. |
608
625
  | `data.purpose` | string | The reason this settlement, site, or structure exists, selected from its placeCharacter tags. |
609
626
  | `data.lore` | list of Addresses | Lore concerning this place — its peoples, its law, its calendar, its history. |
610
627
  | `data.parents` | list of Addresses | Enclosing places this one sits within. |
628
+ | `data.culture` | an Address | The people this place belongs to, as a culture lore note. |
611
629
  | `data.population` | number | Approximate population, to two significant digits. |
612
630
  | `data.government` | an Address or null | The governing affiliation Address; the default target type is affiliation. Explicit null means complete anarchy. A positive population with no government key produces an advisory. |
613
631
  | `data.market` | number | What trade the settlement supports, on a scale of six: 1 hamlet, 2 village, 3 town, 4 market town, 5 city, 6 great city. |
@@ -699,17 +717,17 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
699
717
 
700
718
  **Subtypes:** `rules`, `userguide`, `reference`, `howto`, `concept`, `settingguide`.
701
719
 
702
- | Field | Shape | Meaning |
703
- | ----- | ----- | ------------------------------- |
704
- | — | — | No type-specific `data` fields. |
720
+ | Field | Shape | Meaning |
721
+ | -------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------- |
722
+ | `data.culture` | an Address | The culture a setting guide introduces, as a culture lore note. Required on `settingguide`; no other subType states it. |
705
723
 
706
724
  ### macro
707
725
 
708
726
  **Subtypes:** None.
709
727
 
710
- | Field | Shape | Meaning |
711
- | ----- | ----- | ------------------------------- |
712
- | — | — | No type-specific `data` fields. |
728
+ | Field | Shape | Meaning |
729
+ | ----------- | ---------- | -------------------------------------------------------------------- |
730
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
713
731
 
714
732
  ### bundle
715
733
 
@@ -717,6 +735,7 @@ Lore records in-world knowledge. A `culture` describes a people; a `custom` desc
717
735
 
718
736
  | Field | Shape | Meaning |
719
737
  | --------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
738
+ | `data.icon` | an Address | The document's profile art — an `icon` address, resolved into `img`. |
720
739
  | `data.contents` | list of Addresses | The documents the Adventure holds, as addresses. Empty when unstated. A document of neither `none` nor the system being compiled is left out rather than failing. |
721
740
 
722
741
  ### folder
package/docs/reference/theme-pages.md CHANGED
@@ -137,8 +137,9 @@ a top-level `banner:`, which the theme resolves against `params.cdnBaseURL`
137
137
  one; an unset or `null` value carries on to the next step.
138
138
  2. `banner:` at the top level. `none` (or `false`) declines a hero image; a
139
139
  full URL is used as-is; anything else is a fragment under `images/`.
140
- 3. `images/banners/{subtype}.webp`, where the subtype is the page's `category`
141
- for a `type: doc` page and its `type` otherwise.
140
+ 3. `images/banners/{name}.webp`, where the name comes from the kind mapping
141
+ described below: the banner the page's `type` and `subType` map to, or its
142
+ `category` for a `type: doc` page.
142
143
  4. `images/banners/default.webp` — when the page has no type, **and** whenever
143
144
  the name picked by 2 or 3 is not in the declared inventory.
144
145
 
@@ -157,9 +158,33 @@ either and must not second-guess an address it cannot know about. A step 1
157
158
  address is not checked for the same reason: the question has already been
158
159
  answered upstream.
159
160
 
161
+ **The kind mapping.** `data/banner-kinds.yaml` declares, once, which banner a
162
+ page of each note `type` opens with. A type maps to one banner name for all of
163
+ its subTypes, or to a table that names a banner for every subType the note
164
+ vocabulary declares for it:
165
+
166
+ ```yaml
167
+ categoryTypes:
168
+ - doc
169
+ kinds:
170
+ skill: skills-attributes
171
+ being:
172
+ character: character
173
+ creature: creature
174
+ npc: character
175
+ ```
176
+
177
+ `default` names the default banner as a deliberate choice, and emits no
178
+ warning. A type missing from the file resolves to its own name, so a kind with
179
+ no declared art still produces the missing-banner warning. The lint check and
180
+ the test suite fail on a mapped name that `banners.yaml` does not declare, and
181
+ on a type or subType of the note vocabulary that the mapping omits. A consumer
182
+ publishing its own artwork set ships its own `data/banner-kinds.yaml` beside
183
+ its `data/banners.yaml`.
184
+
160
185
  **One resolver.** The order above lives in `partials/banner-url.html`, which
161
186
  returns a URL or an empty string; `hero-banner.html` calls it with the page's
162
- subtype, for step 2.
187
+ `type`, `subType` and `category`, for step 3.
163
188
 
164
189
  **Keeping the inventory honest.** The lint check over `data/banners.yaml`
165
190
  fetches every declared name from the asset host and fails on any non-200
@@ -169,14 +194,14 @@ list by shipping its own `data/banners.yaml`, which Hugo reads in preference
169
194
  to the theme's bundled one, and can run the same check against it.
170
195
 
171
196
  **Declining a hero image.** `banner: none` on a hand-authored page, and a
172
- blank `data.banner` on a note, render the band with no image at all — the
197
+ blank `data.banner` on a note (which the build emits for `data.banner: none`),
198
+ render the band with no image at all — the
173
199
  title, the palette and the `.hero-with-image` gradient, which is what gives
174
200
  the band its presence. A package may have a standing editorial reason to
175
201
  publish no imagery, and falling back to a default for those would substitute
176
202
  artwork where the considered answer was "none". See
177
203
  [images, icons, audio, and provenance](../authoring/assets.md) for how a note
178
- declines one; the spelling differs from the hand-authored page's, and the two
179
- are not interchangeable.
204
+ declines one with `data.banner: none`.
180
205
 
181
206
  ## Generated sections
182
207