@heroiclands/package-build 22.3.0 → 22.4.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.
- package/CHANGELOG.md +59 -0
- package/CONTENT.md +182 -306
- package/bin/content-build.mjs +40 -23
- package/bin/package-build.mjs +4 -3
- package/content-config.mjs +82 -180
- package/docs/api.md +27 -32
- package/docs/commands.md +54 -19
- package/docs/configuration.md +102 -132
- package/docs/content-format.md +25 -15
- package/docs/getting-started.md +5 -4
- package/docs/project-setup.md +1 -1
- package/engine/content-links.mjs +25 -60
- package/engine/diagnostics.mjs +2 -2
- package/engine/field-reference.mjs +141 -0
- package/engine/homepage.mjs +91 -172
- package/engine/metadata-index.mjs +7 -3
- package/engine/note-vocabulary.mjs +0 -20
- package/engine/pdf-build.mjs +2 -2
- package/engine/site-build.mjs +64 -225
- package/engine/site-config.mjs +15 -53
- package/engine/site-root.mjs +26 -70
- package/package.json +1 -1
- package/types/content-config.d.mts +14 -8
- package/types/engine/content-links.d.mts +12 -23
- package/types/engine/diagnostics.d.mts +2 -2
- package/types/engine/field-reference.d.mts +78 -0
- package/types/engine/homepage.d.mts +51 -91
- package/types/engine/note-vocabulary.d.mts +0 -12
- package/types/engine/site-build.d.mts +28 -129
- package/types/engine/site-config.d.mts +10 -19
- package/types/engine/site-root.d.mts +11 -36
package/docs/commands.md
CHANGED
|
@@ -261,7 +261,7 @@ package-build: `packageKind: documentation` ships no Foundry package, so there i
|
|
|
261
261
|
|
|
262
262
|
**NAME**
|
|
263
263
|
|
|
264
|
-
`package-build site-root` — write the deployment's `_headers
|
|
264
|
+
`package-build site-root` — write the deployment's `_headers`.
|
|
265
265
|
|
|
266
266
|
**SYNOPSIS**
|
|
267
267
|
|
|
@@ -278,13 +278,18 @@ and Cloudflare Pages reads `_headers` and `_redirects` from there and nowhere
|
|
|
278
278
|
else — a copy inside the prefix is published as a text file and never applied.
|
|
279
279
|
Hugo owns everything under the prefix; this owns what sits beside it.
|
|
280
280
|
|
|
281
|
-
|
|
282
|
-
answers on but nobody advertises —
|
|
283
|
-
`pages.dev`,
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
281
|
+
One file is written, `_headers`, and it says one thing: indexing is
|
|
282
|
+
suppressed on every address a deployment answers on but nobody advertises —
|
|
283
|
+
the project's `pages.dev`, the per-deployment `pages.dev`, and the custom
|
|
284
|
+
domain the routing layer fetches — each of which would otherwise compete with
|
|
285
|
+
the canonical URL in search results. No `Cache-Control` is pinned on the
|
|
286
|
+
prefix root: it is the homepage, and a lifetime on it would hold a stale copy
|
|
287
|
+
at the most-linked address after a deploy.
|
|
288
|
+
|
|
289
|
+
No `_redirects` is written: the prefix root _is_ the homepage, which the site
|
|
290
|
+
build writes as the mount's `_index.md`, so nothing redirects. A `_redirects`
|
|
291
|
+
left beside the site by an earlier build is removed, since Pages would apply
|
|
292
|
+
it.
|
|
288
293
|
|
|
289
294
|
The rules are scoped to those hostnames, so a site deployed under a domain of
|
|
290
295
|
its own stays indexable.
|
|
@@ -304,7 +309,6 @@ under the prefix. Otherwise 0.
|
|
|
304
309
|
```
|
|
305
310
|
$ package-build site-root
|
|
306
311
|
✅ Wrote build/site/_headers.
|
|
307
|
-
✅ Wrote build/site/_redirects.
|
|
308
312
|
```
|
|
309
313
|
|
|
310
314
|
**SEE ALSO**
|
|
@@ -1064,6 +1068,29 @@ named. Reads the configured `itemBuilders` registries; writes (or checks)
|
|
|
1064
1068
|
the destination file, or prints to stdout when none is configured and
|
|
1065
1069
|
`--out` is not given.
|
|
1066
1070
|
|
|
1071
|
+
**A destination under `paths.content` gets a complete note, not a typeless
|
|
1072
|
+
page.** The content-tree walk collects every published page by its `type:`,
|
|
1073
|
+
so a generated page filed there needs the envelope every other note carries
|
|
1074
|
+
or the walk drops it silently — no build failure, no page, every wikilink
|
|
1075
|
+
into it dead. So when `--out` (or `docs.itemFields.out`) resolves inside the
|
|
1076
|
+
content tree, the written file carries:
|
|
1077
|
+
|
|
1078
|
+
- `type: doc`, `subType: reference` — out-of-world lookup material, like
|
|
1079
|
+
every other generated reference page;
|
|
1080
|
+
- `shortcode`, derived from the destination's basename — lowercase
|
|
1081
|
+
alphanumerics only, so `item-frontmatter.md` derives `itemfrontmatter` —
|
|
1082
|
+
unless `docs.itemFields.frontmatter.shortcode` gives one;
|
|
1083
|
+
- `name.full`, from the page's title;
|
|
1084
|
+
- `pack: none` — the page publishes to the website and compiles into no
|
|
1085
|
+
compendium document.
|
|
1086
|
+
|
|
1087
|
+
`docs.itemFields.frontmatter` is deep-merged over that envelope, so a
|
|
1088
|
+
consumer may add keys (`description`, `tags`) or override any of the derived
|
|
1089
|
+
ones. `--check` then compares the **whole** file, envelope included — a page
|
|
1090
|
+
committed with a hand-written or stale envelope reads as out of date exactly
|
|
1091
|
+
as a stale body does. A destination outside the content tree gets the page
|
|
1092
|
+
body alone, with no frontmatter, exactly as before.
|
|
1093
|
+
|
|
1067
1094
|
**OPTIONS**
|
|
1068
1095
|
|
|
1069
1096
|
| Positional | Type | Default | Description |
|
|
@@ -1541,23 +1568,31 @@ Writes the whole Hugo source tree under `build/hugo/` — the sibling of
|
|
|
1541
1568
|
`package compile`: the same tree, rendered as pages instead of compiled
|
|
1542
1569
|
into packs. Everything a consumer would otherwise write for itself happens
|
|
1543
1570
|
here: the walk, address derivation, the address index, table expansion,
|
|
1544
|
-
wikilink resolution, code-fence protection, the foreign-manifest merge,
|
|
1545
|
-
|
|
1546
|
-
|
|
1547
|
-
|
|
1571
|
+
wikilink resolution, code-fence protection, the foreign-manifest merge, and
|
|
1572
|
+
the Hugo configuration itself. The consumer's script then runs Hugo over the
|
|
1573
|
+
tree — `hugo --source build/hugo` — and this command never does.
|
|
1574
|
+
|
|
1575
|
+
**A site is its homepage and its pages.** The `type: homepage` note is
|
|
1576
|
+
written as the mount's `_index.md`, so Hugo renders it at
|
|
1577
|
+
`/<contentPackage>/`; every other note is one page at
|
|
1578
|
+
`/<contentPackage>/<type>-<shortcode>/`. Nothing is generated between them —
|
|
1579
|
+
no section directory, no listing, no tag page — and the generated
|
|
1580
|
+
configuration disables the `section`, `taxonomy`, `term` and `RSS` kinds on
|
|
1581
|
+
every site. An index of what the package publishes is a `doc` note carrying a
|
|
1582
|
+
content table, authored where every other page is.
|
|
1548
1583
|
|
|
1549
1584
|
Three things are written, and nothing outside `build/`:
|
|
1550
1585
|
|
|
1551
1586
|
- `build/hugo/hugo.toml`, generated on every run from `package.json`
|
|
1552
1587
|
(`homepage`, `description`, `author`), `package-build.config.yaml`
|
|
1553
|
-
(`packageBuild.manifest.title`, `site.assets`, `site.
|
|
1554
|
-
`site.
|
|
1588
|
+
(`packageBuild.manifest.title`, `site.assets`, `site.notfound`,
|
|
1589
|
+
`site.hugo`), the organisation's constants, the installed
|
|
1555
1590
|
`@heroiclands/hugo-theme`'s location, and the navigation `deps fetch`
|
|
1556
1591
|
cached. Every value's source is listed under
|
|
1557
1592
|
[the generated Hugo configuration](configuration.md#the-generated-hugo-configuration).
|
|
1558
|
-
- `build/hugo/content/`, the content mount — the homepage
|
|
1559
|
-
the content tree's pages below `publish.address.prefix`. Wiped on
|
|
1560
|
-
run.
|
|
1593
|
+
- `build/hugo/content/`, the content mount — the homepage as its `_index.md`,
|
|
1594
|
+
and the content tree's pages flat below `publish.address.prefix`. Wiped on
|
|
1595
|
+
every run.
|
|
1561
1596
|
- `publishDir` pointing Hugo at `build/site/<contentPackage>/`, the
|
|
1562
1597
|
deployment root `package-build site-root` writes beside. Nothing Hugo
|
|
1563
1598
|
reads lands in what is published.
|
|
@@ -1589,7 +1624,7 @@ failed to expand, or a dead wikilink. Otherwise 0.
|
|
|
1589
1624
|
|
|
1590
1625
|
```
|
|
1591
1626
|
$ content-build site
|
|
1592
|
-
[…] wrote 1 homepage(s) + 1 content page(s)
|
|
1627
|
+
[…] wrote 1 homepage(s) + 1 content page(s) to build/hugo/content
|
|
1593
1628
|
[…] wrote build/hugo/hugo.toml
|
|
1594
1629
|
|
|
1595
1630
|
$ content-build site
|
package/docs/configuration.md
CHANGED
|
@@ -727,11 +727,12 @@ How this repository frames the documentation pages it generates.
|
|
|
727
727
|
registry and are the same wherever rendered; everything here is the
|
|
728
728
|
consumer's: heading, orientation, where the page is filed.
|
|
729
729
|
|
|
730
|
-
| Key
|
|
731
|
-
|
|
|
732
|
-
| `docs.itemFields.title`
|
|
733
|
-
| `docs.itemFields.out`
|
|
734
|
-
| `docs.itemFields.preamble`
|
|
730
|
+
| Key | Type | Required | Default |
|
|
731
|
+
| ----------------------------- | -------- | -------- | ---------------------------------------------------------------------- |
|
|
732
|
+
| `docs.itemFields.title` | string | no | none — the page's H1 |
|
|
733
|
+
| `docs.itemFields.out` | string | no | none — without it, the page goes to stdout |
|
|
734
|
+
| `docs.itemFields.preamble` | string[] | no | none — markdown lines between the generated banner and the first table |
|
|
735
|
+
| `docs.itemFields.frontmatter` | object | no | none — extra note frontmatter, deep-merged over the generated envelope |
|
|
735
736
|
|
|
736
737
|
> ``package-build config: `docs.itemFields` must be a mapping.``
|
|
737
738
|
|
|
@@ -744,44 +745,67 @@ consumer's: heading, orientation, where the page is filed.
|
|
|
744
745
|
|
|
745
746
|
> ``package-build config: `docs.itemFields.preamble[<index>]` must be a string.``
|
|
746
747
|
|
|
748
|
+
`frontmatter` is deep-merged over the note envelope written when `out` is
|
|
749
|
+
under the content tree — see [`content-build docs item-fields`](commands.md#content-build-docs-item-fields):
|
|
750
|
+
|
|
751
|
+
> ``package-build config: `docs.itemFields.frontmatter` must be a mapping.``
|
|
752
|
+
|
|
747
753
|
Any other key under `docs.itemFields` is refused:
|
|
748
754
|
|
|
749
|
-
> ``package-build config: `docs.itemFields.<key>` is not a recognized option (expected one of: title, out, preamble).``
|
|
755
|
+
> ``package-build config: `docs.itemFields.<key>` is not a recognized option (expected one of: title, out, preamble, frontmatter).``
|
|
750
756
|
|
|
751
757
|
### `site`
|
|
752
758
|
|
|
753
759
|
**Type:** object · **Optional** · every key defaults to nothing published:
|
|
754
760
|
|
|
755
|
-
| Key
|
|
756
|
-
|
|
|
757
|
-
| `site.base`
|
|
758
|
-
| `site.assets`
|
|
759
|
-
| `site.description`
|
|
760
|
-
| `site.packages`
|
|
761
|
-
| `site.
|
|
762
|
-
| `site.
|
|
763
|
-
| `site.
|
|
764
|
-
| `site.
|
|
765
|
-
| `site.backfillSections` | boolean | `false` |
|
|
766
|
-
| `site.list` | object | `{shortcodes: false}` |
|
|
767
|
-
| `site.notfound` | object | `null` |
|
|
768
|
-
| `site.hugo` | object | `{}` |
|
|
761
|
+
| Key | Type | Default |
|
|
762
|
+
| ------------------ | -------- | ------------------------------------------- |
|
|
763
|
+
| `site.base` | string | `""` |
|
|
764
|
+
| `site.assets` | string | `""`, but required for `content-build site` |
|
|
765
|
+
| `site.description` | string | `""`, but required for `content-build site` |
|
|
766
|
+
| `site.packages` | string[] | `[]` |
|
|
767
|
+
| `site.pass` | string | `""` |
|
|
768
|
+
| `site.passOptions` | object | `{}` |
|
|
769
|
+
| `site.notfound` | object | `null` |
|
|
770
|
+
| `site.hugo` | object | `{}` |
|
|
769
771
|
|
|
770
772
|
How much of a package reaches the web at all is **not** here — it is
|
|
771
|
-
[`publish.site`](#publish). `site` is framing:
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
773
|
+
[`publish.site`](#publish). `site` is framing: which named pass bundle
|
|
774
|
+
supplies the repository's own body rewrites, and the residue of the
|
|
775
|
+
[generated Hugo configuration](#the-generated-hugo-configuration) that is
|
|
776
|
+
genuinely this repository's own.
|
|
777
|
+
|
|
778
|
+
**A site is its homepage and its pages.** The `type: homepage` note is the
|
|
779
|
+
package's front page at `/<contentPackage>/`, and every other note is one page
|
|
780
|
+
at `/<contentPackage>/<type>-<shortcode>/`. Nothing is generated between
|
|
781
|
+
them: no section directory, no listing of a type, no tag page. Every
|
|
782
|
+
structure above the pages — which notes belong together, in what order,
|
|
783
|
+
under which headings — is authored, as a `doc` note carrying a content table
|
|
784
|
+
over the content index, and linked from the homepage like any other page.
|
|
785
|
+
|
|
786
|
+
So a page of documentation is a note — `type: doc`, addressed by its
|
|
787
|
+
shortcode, and `pack: none` where it compiles into no Foundry document — and
|
|
788
|
+
there is no second mechanism for mounting a directory of markdown. A
|
|
789
|
+
configuration that names one is refused with a message saying where the page
|
|
790
|
+
goes instead:
|
|
791
|
+
|
|
792
|
+
> ``package-build config: `site.trees` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and link it from the homepage or from a `doc` note that indexes it.``
|
|
793
|
+
|
|
794
|
+
> ``package-build config: `site.readmeSections` is retired — a page is a note in the content tree. Give each page `type: doc`, a `shortcode` and `pack: none`, file it under `assets/content/`, and link it from the homepage or from a `doc` note that indexes it.``
|
|
795
|
+
|
|
796
|
+
A configuration that asks the build to generate an index between the
|
|
797
|
+
homepage and the pages is refused the same way, by name and with one message
|
|
798
|
+
— `site.sections` (and the `listType` / `listSubType` an entry carried),
|
|
799
|
+
`site.landing`, `site.backfillSections` and `site.list` alike, since how a
|
|
800
|
+
listing renders is a content table's to say:
|
|
775
801
|
|
|
776
|
-
|
|
777
|
-
documentation is a note — `type: doc`, addressed by its shortcode, and
|
|
778
|
-
`pack: none` where it compiles into no Foundry document — so there is no
|
|
779
|
-
second mechanism for mounting a directory of markdown, and a configuration
|
|
780
|
-
that names one is refused with a message saying where the page goes instead:
|
|
802
|
+
> ``package-build config: `site.sections` is retired — a site is its homepage and its pages, and any index between them is a `doc` note: write one with `type: doc`, a `shortcode` and `pack: none`, carrying a content table over the notes it lists, and link it from the homepage. Nothing is generated between the homepage and the pages, so delete the key.``
|
|
781
803
|
|
|
782
|
-
> ``package-build config: `site.
|
|
804
|
+
> ``package-build config: `site.landing` is retired — a site is its homepage and its pages, and any index between them is a `doc` note: write one with `type: doc`, a `shortcode` and `pack: none`, carrying a content table over the notes it lists, and link it from the homepage. Nothing is generated between the homepage and the pages, so delete the key.``
|
|
783
805
|
|
|
784
|
-
> ``package-build config: `site.
|
|
806
|
+
> ``package-build config: `site.backfillSections` is retired — a site is its homepage and its pages, and any index between them is a `doc` note: write one with `type: doc`, a `shortcode` and `pack: none`, carrying a content table over the notes it lists, and link it from the homepage. Nothing is generated between the homepage and the pages, so delete the key.``
|
|
807
|
+
|
|
808
|
+
> ``package-build config: `site.list` is retired — a site is its homepage and its pages, and any index between them is a `doc` note: write one with `type: doc`, a `shortcode` and `pack: none`, carrying a content table over the notes it lists, and link it from the homepage. Nothing is generated between the homepage and the pages, so delete the key.``
|
|
785
809
|
|
|
786
810
|
Where the Hugo tree is written is not a choice. `content-build site` writes
|
|
787
811
|
the whole Hugo source tree under `build/hugo/` — the generated `hugo.toml`,
|
|
@@ -793,7 +817,7 @@ published. A `site.out` is refused by name:
|
|
|
793
817
|
|
|
794
818
|
> ``package-build config: `site` must be a mapping.``
|
|
795
819
|
|
|
796
|
-
> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages,
|
|
820
|
+
> ``package-build config: `site.<key>` is not a recognized option (expected one of: base, assets, description, packages, pass, passOptions, notfound, hugo).``
|
|
797
821
|
|
|
798
822
|
`site.assets` is the host every package's imagery is served from, and it is
|
|
799
823
|
the one address in this file that is not this repository's own. A note names
|
|
@@ -839,62 +863,8 @@ names a registry):
|
|
|
839
863
|
|
|
840
864
|
> ``package-build config: `site.packages[<index>]` must be a non-empty string.``
|
|
841
865
|
|
|
842
|
-
`site.
|
|
843
|
-
|
|
844
|
-
|
|
845
|
-
| Key (under `site.sections.<name>`) | Type | Required | Default |
|
|
846
|
-
| ---------------------------------- | -------------------------- | -------- | ------- |
|
|
847
|
-
| `site.sections.<name>.title` | string | yes | — |
|
|
848
|
-
| `site.sections.<name>.banner` | string | no | none |
|
|
849
|
-
| `site.sections.<name>.description` | string | no | none |
|
|
850
|
-
| `site.sections.<name>.listType` | string, an address segment | no | none |
|
|
851
|
-
| `site.sections.<name>.listSubType` | string, an address segment | no | none |
|
|
852
|
-
|
|
853
|
-
> ``package-build config: `site.sections.<name>` must be a mapping.``
|
|
854
|
-
|
|
855
|
-
> ``package-build config: `site.sections.<name>.title` must be a non-empty string.``
|
|
856
|
-
|
|
857
|
-
`listType` / `listSubType` say what the section **lists** — a content type
|
|
858
|
-
and subType, which are address segments and therefore checked against
|
|
859
|
-
`^[a-z0-9]+$`, deliberately distinct from the section's own name (a URL
|
|
860
|
-
this site chose; `user-guide` is the section, `userguide` the subType):
|
|
861
|
-
|
|
862
|
-
> ``package-build config: `site.sections.<name>.listType` is `Not Ok`, which is not lowercase alphanumeric. It names a content type or subType, and those are address segments (^[a-z0-9]+$) — not the section's own name, which is a URL this site chose and need not match (`user-guide` is the section, `userguide` the subType). A value no page carries selects nothing and leaves the landing empty.``
|
|
863
|
-
|
|
864
|
-
`listSubType` alone, without `listType`, names no query — a subType only
|
|
865
|
-
distinguishes _within_ a type:
|
|
866
|
-
|
|
867
|
-
> ``package-build config: `site.sections.<name>.listSubType` is declared without a `listType`. A subType tells pages apart only within a type — `rules`, `userguide` and `reference` are all `doc` — so on its own it names no query for a layout to run.``
|
|
868
|
-
|
|
869
|
-
Any other key on a section entry is refused:
|
|
870
|
-
|
|
871
|
-
> ``package-build config: `site.sections.<name>.<key>` is not a recognized option (expected one of: title, banner, description, listType, listSubType).``
|
|
872
|
-
|
|
873
|
-
`site.landing` is different from a section entry — it is the mount's own
|
|
874
|
-
landing page frontmatter, passed through verbatim to Hugo rather than
|
|
875
|
-
validated field by field, since its vocabulary is the theme's and not this
|
|
876
|
-
package's:
|
|
877
|
-
|
|
878
|
-
> ``package-build config: `site.landing` must be a mapping.``
|
|
879
|
-
|
|
880
|
-
`site.passOptions` and `site.backfillSections` have no further shape of
|
|
881
|
-
their own — `passOptions` is passed to the resolved `site.pass` bundle
|
|
882
|
-
unchanged, and `backfillSections` is a plain boolean:
|
|
883
|
-
|
|
884
|
-
> ``package-build config: `site.backfillSections` must be a boolean.``
|
|
885
|
-
|
|
886
|
-
`site.list` is how a listing page renders, written into the generated Hugo
|
|
887
|
-
configuration as `params.list`:
|
|
888
|
-
|
|
889
|
-
| Key | Type | Required | Default |
|
|
890
|
-
| ---------------------- | ------- | -------- | ------- |
|
|
891
|
-
| `site.list.shortcodes` | boolean | no | `false` |
|
|
892
|
-
|
|
893
|
-
> ``package-build config: `site.list` must be a mapping.``
|
|
894
|
-
|
|
895
|
-
> ``package-build config: `site.list.shortcodes` must be a boolean.``
|
|
896
|
-
|
|
897
|
-
> ``package-build config: `site.list.<key>` is not a recognized option (expected one of: shortcodes).``
|
|
866
|
+
`site.passOptions` has no further shape of its own — it is passed to the
|
|
867
|
+
resolved `site.pass` bundle unchanged.
|
|
898
868
|
|
|
899
869
|
`site.notfound` is the wording of the "page not found" page, written into
|
|
900
870
|
the generated Hugo configuration as `params.notfound`. The theme renders
|
|
@@ -966,26 +936,25 @@ the block cannot grow into a second configuration file:
|
|
|
966
936
|
`content-build site` writes `build/hugo/hugo.toml` on every run. Every value
|
|
967
937
|
in it has one source, and that source is where it is edited:
|
|
968
938
|
|
|
969
|
-
| Key | Derived from
|
|
970
|
-
| --------------------------------- |
|
|
971
|
-
| `baseURL` | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/`
|
|
972
|
-
| `title` | `packageBuild.manifest.title`, which is required
|
|
973
|
-
| `locale` | the organisation's locale, `en-us`, in `engine/site-config.mjs`
|
|
974
|
-
| `publishDir` | `contentPackage`, under the deployment root `build/site` — written relative to `build/hugo/`, so `../site/<contentPackage>`
|
|
975
|
-
| `contentDir` | the fixed content mount, `build/hugo/content` — written as `content`
|
|
976
|
-
| `themesDir` | where `@heroiclands/hugo-theme` is installed, resolved the way Node resolves a package and written relative to `build/hugo/`
|
|
977
|
-
| `theme` | the installed `@heroiclands/hugo-theme`, so `hugo-theme`
|
|
978
|
-
| `disableKinds` |
|
|
979
|
-
| `taxonomies` | the
|
|
980
|
-
| `outputs` | the
|
|
981
|
-
| `params.description` | `site.description`, which is required
|
|
982
|
-
| `params.author` | `package.json` `author`, its `name`; absent when the package declares none
|
|
983
|
-
| `params.cdnBaseURL` | `site.assets`, which is required
|
|
984
|
-
| `params.brand` | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs`
|
|
985
|
-
| `params.
|
|
986
|
-
| `
|
|
987
|
-
| `
|
|
988
|
-
| `menu` | the navigation `content-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as `parent` entries |
|
|
939
|
+
| Key | Derived from |
|
|
940
|
+
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
941
|
+
| `baseURL` | `package.json` `homepage`, checked by `checkHomepage` — an absolute URL ending `/<contentPackage>/` |
|
|
942
|
+
| `title` | `packageBuild.manifest.title`, which is required |
|
|
943
|
+
| `locale` | the organisation's locale, `en-us`, in `engine/site-config.mjs` |
|
|
944
|
+
| `publishDir` | `contentPackage`, under the deployment root `build/site` — written relative to `build/hugo/`, so `../site/<contentPackage>` |
|
|
945
|
+
| `contentDir` | the fixed content mount, `build/hugo/content` — written as `content` |
|
|
946
|
+
| `themesDir` | where `@heroiclands/hugo-theme` is installed, resolved the way Node resolves a package and written relative to `build/hugo/` |
|
|
947
|
+
| `theme` | the installed `@heroiclands/hugo-theme`, so `hugo-theme` |
|
|
948
|
+
| `disableKinds` | the toolchain, which renders a site as its homepage and its pages: `["section", "taxonomy", "term", "RSS"]` on every site, whatever its notes carry |
|
|
949
|
+
| `taxonomies` | the toolchain — never written, because `taxonomy` and `term` are disabled kinds |
|
|
950
|
+
| `outputs` | the toolchain — never written, because every listing kind is disabled |
|
|
951
|
+
| `params.description` | `site.description`, which is required |
|
|
952
|
+
| `params.author` | `package.json` `author`, its `name`; absent when the package declares none |
|
|
953
|
+
| `params.cdnBaseURL` | `site.assets`, which is required |
|
|
954
|
+
| `params.brand` | the organisation's brand links — `logo`, `licenseURL`, `discordURL` — in `engine/site-config.mjs` |
|
|
955
|
+
| `params.notfound` | `site.notfound`; absent when undeclared |
|
|
956
|
+
| `markup.goldmark.renderer.unsafe` | the toolchain, whose pages carry raw HTML — a `<figure>` for every image, a `<span>` marking an unresolved link |
|
|
957
|
+
| `menu` | the navigation `content-build deps fetch` caches from `https://www.heroiclands.org/nav.json`, entry for entry, a dropdown's entries as `parent` entries |
|
|
989
958
|
|
|
990
959
|
The site build reads the navigation from the cache only. A cold cache is an
|
|
991
960
|
error naming the command that fills it:
|
|
@@ -1012,13 +981,13 @@ build the same way:
|
|
|
1012
981
|
|
|
1013
982
|
> ``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
983
|
|
|
1015
|
-
Nothing else is emitted.
|
|
1016
|
-
|
|
1017
|
-
|
|
1018
|
-
|
|
1019
|
-
|
|
1020
|
-
|
|
1021
|
-
|
|
984
|
+
Nothing else is emitted. `home` and `page` are the only kinds a site
|
|
985
|
+
renders: the homepage is the mount's `_index.md`, every note is a page, and
|
|
986
|
+
`section`, `taxonomy`, `term` and `RSS` are disabled on every site — so no
|
|
987
|
+
`[taxonomies]` or `[outputs]` is written, Hugo's default taxonomy pair never
|
|
988
|
+
applies, and a note's `tags:` reach the page's front matter and nothing
|
|
989
|
+
else. A tag is a field a content table filters on, not a page of its own.
|
|
990
|
+
Every other key is `site.hugo`'s to add.
|
|
1022
991
|
|
|
1023
992
|
### `pdf`
|
|
1024
993
|
|
|
@@ -1326,9 +1295,8 @@ its content tree's addresses mount inside the package.
|
|
|
1326
1295
|
Every HeroicLands package publishes at least an authored homepage at
|
|
1327
1296
|
`https://www.heroiclands.org/<contentPackage>/` — there is no value meaning
|
|
1328
1297
|
_no web presence at all_. `homepage` is the floor: the authored homepage
|
|
1329
|
-
and nothing else, no content-tree walk
|
|
1330
|
-
|
|
1331
|
-
publishes. `publishesContentPages(config)`, exported from
|
|
1298
|
+
and nothing else, no content-tree walk. `content` is the homepage plus every
|
|
1299
|
+
page the content tree publishes. `publishesContentPages(config)`, exported from
|
|
1332
1300
|
`content-config.mjs` alongside [`compilesFoundryDocuments`](#packagekind),
|
|
1333
1301
|
answers the one question every reader of the mode actually asks — the site
|
|
1334
1302
|
build, to decide whether to walk the tree at all, and the content index, to
|
|
@@ -1700,17 +1668,19 @@ the source directory:
|
|
|
1700
1668
|
|
|
1701
1669
|
## Every retired or forbidden key, in one place
|
|
1702
1670
|
|
|
1703
|
-
| Key
|
|
1704
|
-
|
|
|
1705
|
-
| `publish.address.landing`
|
|
1706
|
-
| `packs[].folders`
|
|
1707
|
-
| `rootDir`
|
|
1708
|
-
| `foundryPackage`
|
|
1709
|
-
| `homepage`, `author`
|
|
1710
|
-
| `stats.systemId`
|
|
1711
|
-
| `stats.systemVersion`
|
|
1712
|
-
| `packageBuild.manifest.id`, `.version`, `.description`, `.url`, `.bugs`, `.manifest`, `.download`, `.compatibility`, `.relationships`, `.packs`
|
|
1713
|
-
| `site.out`
|
|
1714
|
-
| `site.
|
|
1715
|
-
| `
|
|
1716
|
-
| `
|
|
1671
|
+
| Key | Why |
|
|
1672
|
+
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
1673
|
+
| `publish.address.landing` | Retired — named a whole-section landing, and there are no sections to address. |
|
|
1674
|
+
| `packs[].folders` | Retired — a folder is a note (`type: folder`), materialised by the pack whose documents reference it. |
|
|
1675
|
+
| `rootDir` | Forbidden in a YAML configuration — always the file's own directory. |
|
|
1676
|
+
| `foundryPackage` | Forbidden in a YAML configuration — always the adjacent `package.json` `name`. |
|
|
1677
|
+
| `homepage`, `author` | Forbidden in a YAML configuration — always the adjacent `package.json`'s own `homepage` and `author`. |
|
|
1678
|
+
| `stats.systemId` | Forbidden in every configuration — derived from `packageKind`, `requiresSystem` or a lone declared system. |
|
|
1679
|
+
| `stats.systemVersion` | Forbidden in every configuration — derived from `package.json` (a system) or `systems:` / `relationships.systems` (a module). |
|
|
1680
|
+
| `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). |
|
|
1681
|
+
| `site.out` | Retired — the site build writes its content mount at `build/hugo/content`, beside the generated `hugo.toml`. |
|
|
1682
|
+
| `site.trees`, `site.readmeSections` | Retired — a page is a note in the content tree. |
|
|
1683
|
+
| `site.sections`, `site.landing`, `site.backfillSections`, `site.list` | Retired — a site is its homepage and its pages, and any index between them is a `doc` note. |
|
|
1684
|
+
| `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). |
|
|
1685
|
+
| `publish.site: true` / `publish.site: false` | Refused rather than mapped — write `homepage` or `content`. |
|
|
1686
|
+
| `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
CHANGED
|
@@ -2249,11 +2249,26 @@ A SoHL "being" document will be created, as will an "HM3" document.
|
|
|
2249
2249
|
|
|
2250
2250
|
### type: homepage
|
|
2251
2251
|
|
|
2252
|
-
|
|
2253
|
-
|
|
2254
|
-
|
|
2255
|
-
|
|
2256
|
-
It
|
|
2252
|
+
The package's front page, published at `https://www.heroiclands.org/<package>/`.
|
|
2253
|
+
Exactly one note in a content tree declares this type, and it compiles into
|
|
2254
|
+
no Foundry document: it is a page and nothing else.
|
|
2255
|
+
|
|
2256
|
+
It declares a `shortcode` — conventionally `root` — because that is what a
|
|
2257
|
+
link is written with: `[[homepage-root|Text]]` is an ordinary wikilink, and it
|
|
2258
|
+
resolves to `/<package>/`. The shortcode names the page in links; its address
|
|
2259
|
+
is the package root. `title` defaults to `packageBuild.manifest.title`; a
|
|
2260
|
+
`description` and a `banner` are read by the theme's hero; any other
|
|
2261
|
+
top-level key is passed through to the page as a theme parameter.
|
|
2262
|
+
|
|
2263
|
+
The page is its body, published verbatim: no wikilink is resolved on it and
|
|
2264
|
+
no table expanded, so its links are markdown links, package-relative
|
|
2265
|
+
(`kb/rules/`) or external. An index of what the package publishes is not
|
|
2266
|
+
written here and is not generated anywhere — it is a `doc` note carrying a
|
|
2267
|
+
content table, linked from this page like any other.
|
|
2268
|
+
|
|
2269
|
+
Two top-level keys are refused, because neither decides anything on a page:
|
|
2270
|
+
`id`, the Foundry document id a compendium UUID is built from, and `landing`,
|
|
2271
|
+
a card block — the homepage is a page with a body, rendered as one.
|
|
2257
2272
|
|
|
2258
2273
|
### type: vehicle
|
|
2259
2274
|
|
|
@@ -3137,21 +3152,16 @@ any other, and the audience is the section it sits in.
|
|
|
3137
3152
|
Write `type: doc`, `subType: reference`, `shortcode: <type>` — so the
|
|
3138
3153
|
affiliations introduction is `doc-affiliation`, addressed and linked like
|
|
3139
3154
|
anything else, and typically carrying a generated table of what it introduces.
|
|
3140
|
-
It has no build path of its own
|
|
3141
|
-
|
|
3155
|
+
It has no build path of its own, and it is the only kind of index there is: a
|
|
3156
|
+
site is its homepage and its pages, and nothing is generated between them.
|
|
3142
3157
|
|
|
3143
|
-
There is no landing page and no section. A
|
|
3144
|
-
section's landing, and a `subType: collection` note with a top-level `section:`
|
|
3145
|
-
key was a second way to say the same thing. All of it is retired, because a
|
|
3146
|
-
section appears in **no address**: a
|
|
3158
|
+
There is no landing page and no section. A section appears in **no address**: a
|
|
3147
3159
|
page publishes at `/<package>/<type>-<shortcode>/`, which names no directory. A
|
|
3148
3160
|
section is what Hugo calls a content directory, and the note format does not
|
|
3149
3161
|
carry one.
|
|
3150
3162
|
|
|
3151
|
-
So a `doc`'s `subType` is a **genre** and nothing else, closed to the
|
|
3152
|
-
|
|
3153
|
-
landing's `subType` named the section it addressed; with no landings, one field
|
|
3154
|
-
has one reading again.
|
|
3163
|
+
So a `doc`'s `subType` is a **genre** and nothing else, closed to the values
|
|
3164
|
+
above.
|
|
3155
3165
|
|
|
3156
3166
|
### type: macro
|
|
3157
3167
|
|
package/docs/getting-started.md
CHANGED
|
@@ -780,10 +780,11 @@ values, and the content mount — for `hugo --source build/hugo` to render
|
|
|
780
780
|
into `build/site/<contentPackage>/`. There is no Hugo configuration to
|
|
781
781
|
write: the file is generated on every run, and what is genuinely the
|
|
782
782
|
package's own — the wording of its "page not found" page — goes in the
|
|
783
|
-
`site:` block as `site.notfound`. Set `publish.site: content
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
783
|
+
`site:` block as `site.notfound`. Set `publish.site: content`, and the same
|
|
784
|
+
command publishes the content tree's every page beside the homepage — one
|
|
785
|
+
page per note, and nothing generated between them; an index of what the
|
|
786
|
+
package publishes is a `doc` note carrying a content table.
|
|
787
|
+
[`project-setup.md`](project-setup.md) gives the npm scripts.
|
|
787
788
|
|
|
788
789
|
**Another package's content.** Declare a dependency under `relationships`, and
|
|
789
790
|
`content-build deps fetch` caches that release's published content index so
|
package/docs/project-setup.md
CHANGED
|
@@ -254,7 +254,7 @@ package carries this group:
|
|
|
254
254
|
`build:site-content` writes the whole Hugo source tree under `build/hugo/` —
|
|
255
255
|
the generated `hugo.toml` and the content mount — with `content-build site`;
|
|
256
256
|
`build:site-html` runs Hugo over it, rendering into `build/site/<contentPackage>/`;
|
|
257
|
-
`build:site-root` writes the deployment's `_headers`
|
|
257
|
+
`build:site-root` writes the deployment's `_headers` beside
|
|
258
258
|
that; and `serve:site` does the first and then `hugo server` for a live
|
|
259
259
|
preview. The repository carries no Hugo configuration of its own: `hugo.toml`
|
|
260
260
|
is generated on every run from `package.json`, `package-build.config.yaml`,
|