@heroiclands/package-build

The shared toolchain for building HeroicLands Foundry systems and modules. It compiles Markdown content into a searchable index, Foundry compendiums, website pages, and a book; it also assembles manifests, assets, bundles, and release archives.

Start here

Use Node 24 or newer and npm. Initialize a project before it has a package.json, or add the package to an existing repository:

npm exec --package=@heroiclands/package-build -- package-build init my-package --kind modules --name my-package --title "My Package" --description "A content package." --author "Your Name" --license original

npm install -D @heroiclands/package-build

The generated project includes a homepage, website and book targets, npm scripts, and a local .gitignore. Getting started routes you to a system, module, or content authoring path. The content-language-server provides editor navigation and completion.

Working on this repository

Run npm ci in each fresh clone or worktree. Its prepare step installs the committed .githooks/ with git config core.hooksPath .githooks; run npm run prepare to install the hooks again without reinstalling dependencies. Git uses the hook files in the current worktree.

These are the canonical POSIX shell hooks from HeroicLands/.github. They need Git, POSIX utilities and an available UTF-8 locale, and run without Node at commit time. pre-commit refuses commits on main and master; commit-msg refuses assistant coauthor credits and standalone assistant signatures while allowing ordinary prose and human coauthors. Both forges run the pinned canonical drift action against every installed hook file.

Local opt-outs use Git configuration: hooks.protectedBranch false or hooks.allowCommitOnMain true for the branch guard, and hooks.noAttribution false for the message guard. Prefix each with git config to set it for this clone. git commit --no-verify skips both checks once. Server and pull-request enforcement still apply.

The published githooks/ bundle is a separate optional API described in project setup. This repository’s setup installs the two canonical shell hooks; it installs no pre-push hook. Run npm test and the other checks directly, or use package-build ci for a container run.

Documentation

The documentation lives in the Markdown files in this repository. Start with the documentation home. This toolchain does not build its own site or book. A Hugo theme dependency would form a cycle because the theme uses package-build for releases.

| Topic | Guide | | ------------------------------------------------- | ------------------------------------------------------------------------- | | Documentation landing | Home | | Project layout and scripts | Project setup | | Note model and output | Content format | | Frontmatter and system blocks | Frontmatter | | Addresses, links, anchors, SQL, and secret blocks | Links and markup | | Images, icons, audio, and provenance | Assets | | Dates, calendars, and eras | Dates and calendars | | Complete note fields and mappings | Note types | | Detailed format rules and examples | Format details | | Compendium routing and document builds | Packs | | Website build and publication | Site | | What the theme draws on a page | Theme pages | | PDF book build | Book | | Icon generation and use | Icons | | Reference pages and content indexes | Reference pages | | Localization and templates | Localization | | Foundry integration testing | End-to-end testing, including an optional S3 server | | Release and deployment | Release and deploy | | Every CLI command | Commands | | Every build setting | Configuration | | Programmatic exports | API | | Error locations and severities | Diagnostics | | Architectural rationale | Design |

Place notes may declare a governing affiliation with data.government (Address, default target type affiliation), or explicit null for complete anarchy. Positive population with an omitted government produces an advisory. See place governments.

Every icon and image is covered by a provenance record stating attribution, license and ai. A Foundry package ships only the pictures whose record says ai: false under a licence on the shipping list, staged flat at the package root as icons/<basename> and images/<basename> and listed in its asset set, asset-sets/default.json; a reference to a picture it leaves out draws the package's missing stand-in, and every compiled reference states its asset's address. See assets and what a package ships.

package-build cdn publish --set <file> --name <display name> uploads every icon and image the package has, shipped or not, to <site.assets>/<contentPackage>/ in that flat layout, and writes the named set listing the pictures the package leaves out. It reads the bucket from CDN_ENDPOINT, CDN_BUCKET, CDN_ACCESS_KEY_ID and CDN_SECRET_ACCESS_KEY, in the environment or .env.local. See publish pictures to the CDN.

Leading captions, generic fenced divs, inline spans, and poetry code fences are described in links and markup.

Cypress end-to-end suites use pinned Chrome for Testing 155.0.8059.84 by default on macOS arm64 and Linux x64, downloaded once into a reusable cache. Select an installed browser with package-build e2e fast -- --browser electron (also available for run and open). See browser selection and cache settings.

The package is GPL-3.0-or-later for code and CC-BY-SA-4.0 for original content. See LICENSE.md.