@heroiclands/package-build 22.15.0 → 22.16.0

package/docs/authoring/assets.md

@@ -0,0 +1,31 @@
+---
+shortcode: authoringassets
+name: { full: "Images, icons, audio, and provenance" }
+type: doc
+subType: howto
+---
+
+# Images, icons, audio, and provenance
+
+An addressable file lives under one of three roots. Subdirectories beneath each root are for author organization and can change without changing the asset Address.
+
+| Root            | Address type | Typical use                          |
+| --------------- | ------------ | ------------------------------------ |
+| `assets/images` | `image`      | Maps, portraits, and illustrations.  |
+| `assets/icons`  | `icon`       | Item and being icons.                |
+| `assets/audio`  | `audio`      | Sound attached to content or scenes. |
+
+The file's name without its extension is its shortcode; the root determines the type. Asset Addresses use system `none`. A regular link defaults to `note`, but `![[icon-harbor|Harbor emblem]]` defaults to `none`. Image and icon addresses used by `data.icon`, `data.banner`, and other art fields also default to `none`. Those fields name the asset as a bare Address, without wikilink brackets.
+
+```markdown
+![[image-harbor-map|Map of the harbor]]{size=large}
+![[icon-harbor|Harbor emblem]]{float=top-left size=medium}
+```
+
+The embed's label is alternative text. `![[icon-harbor|]]` is decorative. `size=auto` follows the file's natural size; named sizes let web, Foundry, and book choose suitable dimensions. Use `.full-width` for an image intended to span the available measure. The [image reference](../reference/format-details.md#images) lists the closed directive values.
+
+## Ownership and source records
+
+Record provenance for the assets you ship. Put `provenance.yaml` in an asset directory to describe files there and below, or put a YAML sidecar beside one asset to give that file its own record. A sidecar takes precedence over a directory record for that asset. An asset with no record still enters the index with blank provenance fields. Keep attribution with the authored asset so movement through the tree does not lose its source or license. See the [asset record reference](../reference/format-details.md#the-asset-record) for the accepted keys, inheritance, and examples.
+
+The build writes transformed or optimized copies under `build/`; the authored file remains the input for the next build. Output paths are derived from the owning package, asset type, and build target. The [icon guide](../guides/icons.md) covers generated icon variants and placement in Foundry.

package/docs/authoring/dates-and-calendars.md

@@ -0,0 +1,33 @@
+---
+shortcode: authoringdatesandcalendars
+name: { full: "Dates, calendars, and eras" }
+type: doc
+subType: howto
+---
+
+# Dates, calendars, and eras
+
+A canonical date names a day without assuming how a culture divides a year. Write `<year>.<day>[:HHMMSS]`: `720.136` is day 136 of year 720, and `720.136:143005` adds a 24-hour time. A negative year is valid. The day must fit the world's declared year length. The dot separates year from **day of year**, not month from day.
+
+Authors can instead write a named calendar date in frontmatter:
+
+```yaml
+data:
+  born: datefrom vrcal 23 Taranis 326 VR
+  died: ~326.114
+```
+
+`datefrom` takes a calendar shortcode or Address, then the date in that calendar. The calendar defines month names and eras. A date can have day, month, or year precision. Prefix either spelling with `~` for an approximate date. `unknown` means an occurrence is known but its date is not recorded, in fields that accept it. These are the frontmatter date forms; do not put a Handlebars expression there.
+
+A calendar defines the order and length of months. An era defines where a year count begins. One calendar can have several eras; a multi-era date names its era. Era starts increase on the canonical timeline, with gaps allowed. Dates before the first era use a negative year in that first era; later eras count forward from their own year 1. There is no year zero. A date in a gap has no named era in that calendar.
+
+Use the CLI to inspect a conversion:
+
+```bash
+package-build datefrom vrcal '23 Taranis 326 VR'
+package-build dateto vrcal 326.114
+```
+
+`datefrom` prints the canonical value; `dateto` prints a named date in the era covering it. The [detailed calendar rules](../reference/format-details.md#dates-and-calendars) explain precision, era markers, bounds, and resolution errors.
+
+In prose, `{{dateformat "vrcal" data.born}}` renders a date in the chosen calendar. `{{dateformat data.calendar data.born}}` uses the note's own calendar Address. A being or place can set `data.calendar`; a being's infobox displays its dates in that calendar, and a place's infobox displays its `present` there.

package/docs/authoring/first-note.md

@@ -0,0 +1,48 @@
+---
+shortcode: authoringfirstnote
+name: { full: "Your first content note" }
+type: doc
+subType: howto
+---
+
+# Your first content note
+
+A HeroicLands content tree lives under `assets/content/`. Put notes in whatever subfolders help you work: the build discovers them recursively and identifies each by frontmatter, not by its directory. This example works in a project made by [`package-build init`](../commands.md#package-build-init-directory).
+
+Create `assets/content/Places/Harbor.md`:
+
+```markdown
+---
+shortcode: harbor
+name: { full: Harbor }
+type: lore
+subType: concept
+---
+
+# Harbor
+
+A sheltered place where ships load and unload.
+```
+
+`shortcode` and `type` identify a HeroicLands note; `name.full` gives readers its name. The YAML ends at the second `---`. Everything after it is the shared Markdown body. Run `npm run lint` to check the note, then `npm run build:site` to build its web page. `npm run serve:site` serves the site locally; `npm run build:book` builds the book. A Foundry package's `npm run build:db` also compiles its configured packs. The generated project supplies these scripts and their configuration.
+
+For optional writing suggestions, run `npx package-build prose lint assets/content/Places/Harbor.md`. This reports difficult sentences and simpler word choices with line and column numbers. It does not change the note or run as part of `npm run lint`. The [prose analysis command](../commands.md#package-build-prose-lint-path) explains the settings and how to read each suggestion.
+
+## What the note becomes
+
+| Output                       | What it contains                                                                                                                        |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Content index                | The note Address, frontmatter, anchors, and links, for search and queries.                                                              |
+| JournalEntry                 | The shared prose, independent of a game system.                                                                                         |
+| JournalEntryPage             | One page per H1, plus an introduction page if prose comes before the first H1. An explicitly anchored lower heading also starts a page. |
+| Website                      | A page at the note's Address when the package publishes content.                                                                        |
+| Book                         | The same content when selected by the book's document tree.                                                                             |
+| Actor, Item, Scene, or Macro | A game document when the type and a system block request one.                                                                           |
+
+The full Address is `<package>-note-lore-harbor`; `<package>` comes from `contentPackage` in `package-build.config.yaml`. In another note, `[[lore-harbor|Harbor]]` links to it. `[[lore-harbor|]]` asks the renderer to use the target's current name. The pipe is required.
+
+## Grow the note only when needed
+
+Add `description` for a short page summary, `tags: [draft]` to mark unfinished prose, or `data` for fields the note's type permits. A system block such as `sohl:` or `hm3:` adds mechanics and can produce a Foundry Actor or Item. It does not replace the shared prose or make another JournalEntry. [Frontmatter](frontmatter.md) explains the allowed keys, and the [note-type reference](../reference/note-types.md) lists every type-specific field.
+
+A note with an empty body is a stub. It remains addressable as data, while a document that would have no content is omitted. See [note states](../reference/format-details.md#three-states-of-a-note) for the precise emission rules.

package/docs/authoring/frontmatter.md

@@ -0,0 +1,40 @@
+---
+shortcode: authoringfrontmatter
+name: { full: "Frontmatter and system blocks" }
+type: doc
+subType: howto
+---
+
+# Frontmatter and system blocks
+
+HeroicLands notes begin with YAML frontmatter. A file is recognized as a note when its opening frontmatter has nonempty `shortcode` and `type` values. Ordinary Markdown files need neither. Keep top-level keys in this order, omitting keys that do not apply: `shortcode`, `name`, `type`, `subType`, `description`, `tags`, `data`, `hm3`, `sohl`. Any other top-level key is an error.
+
+```yaml
+---
+shortcode: harbor
+name: { full: Harbor, aliases: [The Harbor] }
+type: lore
+subType: concept
+description: A sheltered trading port.
+tags: [draft]
+data: {}
+---
+```
+
+`name.full` is the displayed name; `name.aliases` helps search. `description` is the short page summary. `tags` hold draft state and classification. `data` holds facts about the subject shared by systems. A YAML comment is the place for an author-only note: commented values remain valid YAML but do not enter the content index or generated documents.
+
+Use `tags: [gm]` for a note intended only for the GM. It is absent from the public website and book. Foundry includes it only when its document routes to a pack with `private: true`. A note with `gm` that also creates a prose JournalEntry needs a private JournalEntry pack. Links from untagged notes to GM notes are errors; GM notes may link to one another.
+
+The formatter keeps a collection on one line when the full line is under 100 characters. Longer collections use full YAML block form. Run `package-build format --write` to apply key order and collection formatting.
+
+## Shared facts and game mechanics
+
+The [note-type reference](../reference/note-types.md) lists every field accepted under `data`, including the shared `id`, `pack`, `packFolder`, `harnworld`, `icon`, and `banner` fields. A type such as `being` also has its own fields, including `culture`, `homes`, and `affiliations`. A field absent from a type's vocabulary is a lint error; an unrelated field is not silently repurposed.
+
+A `sohl:` or `hm3:` block holds values for that Foundry system. Its `system:` child contains values sent to the system's DataModel. The system block can override shared routing and art where the declared field permits it. `data.pack` and `data.packFolder` are shared routes; a system-specific route belongs in that system block. The [detailed mapping reference](../reference/format-details.md#mappings-every-type-shares) and [system-block explanation](../reference/format-details.md#frontmatter-has-three-regions) cover precedence and emitted fields.
+
+One body describes the subject for both systems. A being's `{#appearance}` and `{#dossier}` sections feed SoHL Actor `system.appearance` and `system.dossier`, and HM3 Actor `system.description` and `system.biography`. An Item's `{#description}` page becomes a shared JournalEntryPage. Its resolved `@UUID[...]` pointer is stored in SoHL Item `system.docHtml` and HM3 Item `system.description`. An Item with no `{#description}` anchor uses its first page. Other H1 pages remain linkable.
+
+## Publication and summaries
+
+A note infobox draws from shared `data`. A system infobox draws from the system's fields, and a mapped system with no document says “Not available.” The same authored body appears in Foundry, on the website, and in the book; presentation adapts to each medium. [Infobox details](../reference/format-details.md#the-infobox) describe field order and empty values.

package/docs/authoring/links-and-markup.md

@@ -0,0 +1,137 @@
+---
+shortcode: authoringlinksandmarkup
+name: { full: "Addresses, links, and body markup" }
+type: doc
+subType: howto
+---
+
+# Addresses, links, and body markup
+
+An Address names content independently of its filename or folder. Its full form is `<package>-<system>-<type>-<shortcode>`. A regular prose link defaults to system `note`, and an asset embed defaults to system `none`. Omitted segments take their defaults from the writing context; a short form must still resolve unambiguously. Frontmatter fields that declare an Address contain the bare Address, without brackets.
+
+```markdown
+[[lore-harbor|Harbor]]
+[[thalorna-note-lore-harbor|]]
+![[icon-harbor|Harbor emblem]]{float=top-left size=medium}
+```
+
+The part after `|` is the displayed link text or an embed's alternative text. An empty label uses the target's current name in a regular link and marks an embed decorative. A missing pipe is an error. Search may use `name.full` and aliases; authored links use Addresses. The [Address reference](../reference/format-details.md#addresses) explains short forms, package qualification, and ambiguity diagnostics.
+
+A link to a note tagged `draft` retains its target and carries a visible draft cue. In a book, the cue reads `(draft)` after the link. A link that resolves nowhere produces a diagnostic and reads `(unresolved link)` after its label in the book.
+
+## Journal pages and anchors
+
+Every H1 starts a JournalEntryPage. A lower-level heading with an explicit anchor starts a page too. Use `{#slug}` to make a stable target:
+
+```markdown
+# The Harbor {#harbor}
+
+The harbor faces west.
+
+## Customs House {#customs-house}
+
+Travelers present their papers here. See [[#harbor|the harbor]].
+```
+
+Another note can link to `[[lore-harbor#customs-house|Customs House]]`. The special Actor anchors `{#appearance}` and `{#dossier}` feed the same authored sections to each system's Actor fields. For Items, `{#description}` selects the JournalEntryPage both systems reference. A map note can use an anchored heading for a scene pin; the compiler replaces the pin's exported JournalEntry and page IDs with the built note's IDs and uses the heading text as its label. See [map notes](../reference/format-details.md#type-map) for scene fields.
+
+## Captions and numbered references
+
+A caption fence labels the next Markdown block. Give it an ID so prose can refer to the block without hard-coding its number:
+
+````markdown
+Refer to [[#trade|]] for the market routes.
+
+:::caption {#trade}
+Regional trade routes
+:::
+
+```sql
+SELECT name.full AS "Market" FROM notes WHERE type = 'place'
+```
+````
+
+The table displays **Table 1: Regional trade routes**, and the reference displays **Table 1**. The number is assigned by the output. An explicit link label, such as `[[#trade|the trade table]]`, displays the written label. A caption can precede a code fence, table, image, or any prose block. An ordinary code fence is code; an SQL result is a table; an image is a figure; every other block is prose. Web pages and Foundry journals number each kind within the note. Books number each kind across the book in reading order. A caption needs a unique ID, nonempty text, a closing `:::`, and a following block.
+
+## Images and protected content
+
+An image or icon embed stands on its own line. `size` accepts `auto`, `small`, `medium`, `large`, and `xlarge`; the medium maps those names to suitable dimensions. `float` controls placement. The asset remains an Address, so moving the file within its asset root does not change the link. See [assets](assets.md) and [image directives](../reference/format-details.md#images).
+
+A `:::secret` block marks GM material while keeping it in the same authored note:
+
+```markdown
+:::secret
+The harbor master is working for the smugglers.
+:::
+```
+
+Players who deliberately inspect source or generated output may see it; the block is a presentation distinction, not access control. The [detailed reference](../reference/format-details.md#what-a-note-produces) describes each medium's handling.
+
+Use `:::info` for a neutral note and `:::warn` for a caution. Both render as
+labelled, colored boxes on the web and in Foundry, and as print boxes in a book:
+
+```markdown
+:::warn
+The bridge closes during the spring flood.
+:::
+```
+
+An optional `{#id}` gives the box an HTML anchor. These blocks need a closing
+`:::` and cannot be nested.
+
+## Footnotes and definition lists
+
+Write a footnote reference as `[^id]` and its definition as `[^id]: text`.
+The ID can be a number or word without spaces or tabs. It connects the
+reference to its definition within one Markdown note; another note can reuse
+the same ID for a different footnote. Rendered markers are numbers assigned in
+the order of first reference, including when the authored ID is a word.
+
+```markdown
+The road is passable in summer.[^season] The bridge has a toll.[^2]
+
+[^season]: Spring flooding closes it for several weeks.
+
+[^2]: The toll is collected at the eastern gate.
+```
+
+Definitions can appear anywhere at the top level of the note. Indent a
+following paragraph or code block by four spaces to include it in the same
+footnote. Keep definitions outside lists, block quotes, and tables. On the web,
+linked footnotes appear in a Footnotes section at the bottom of the HTML page.
+In Foundry, each JournalEntryPage places its referenced footnotes in a Footnotes
+section at the bottom of that page; definitions remain available across pages
+of the same note. In a book, footnotes appear in smaller type at the bottom of
+the page that contains their reference.
+
+A definition list gives a term one or more definitions:
+
+```markdown
+Janapada
+: A territorial community with its own institutions.
+: Also the land associated with that community.
+```
+
+The web and Foundry render a definition list with HTML `<dl>`, `<dt>`, and
+`<dd>` elements. The book renders it as a term list.
+
+## Tables and expressions
+
+Use a SQL fence to render a table from the content index. The table reads frontmatter from indexed notes. A zero-row result is an error unless the fence explicitly permits an empty result.
+
+````markdown
+```sql
+SELECT name.full AS "Name" FROM notes WHERE type = 'lore' ORDER BY name.full
+```
+````
+
+Inline expressions can read the note, format dates, combine values, or run scalar SQL:
+
+```markdown
+{{name.full}} was born on {{dateformat "vrcal" data.born}}.
+There are {{words (sql "SELECT COUNT(*) FROM notes WHERE type = 'being'")}} beings.
+The index contains {{digits (sql "SELECT COUNT(*) FROM entries")}} entries.
+{{and (gt 3 5) (lt 4 2)}}
+```
+
+Use `{{dateformat data.calendar data.born}}` when the note supplies a calendar Address. SQL fences produce tables; the `sql` helper returns one value for an inline expression. Wrap a numeric result in `words` for running prose or `digits` for a grouped numeral. See [date rules](dates-and-calendars.md) and [SQL details](../reference/format-details.md#content-tables) for query options.