Content Pack Checklist
This site is a template; the content pack decides what it actually is. Swapping the subject means replacing three things and touching zero lines of the template layer. This checklist is the result of an actual run: an entirely different content pack was built once with the template files byte-for-byte identical.
1. Edit the config layer
One file only: site.config.js.
| Field | What to set |
|---|---|
siteId | Namespace for the new site (subscription tag prefix, search index, entitlement table are all scoped by it) |
title / tagline / navbarTitle / footerText | Site identity |
content.root / content.topicSlug | Content directory and section slug |
subject.field / labelZh / labelEn / versions / publishedVersions / defaultVersion | The dimension that varies per subject: engine version, edition, school, dynasty |
tagGroups | Tag groups for subscriptions and filtering |
changelog.kinds / labels | Changelog category words and field names |
llms.title / description / notes / preferredPaths | Site summary and starting points for llms.txt |
search.indexPrefix | Search index ownership |
ui.* | Interface copy, always as {zh, en} pairs |
2. What the content pack must contain
| Required | Why |
|---|---|
One doc at the docs/ root with slug: / | The navbar home item points at /. Without it the build fails with Broken link -> / — a broken link, not a styling issue |
One _category_.json per top-level directory | The second navbar row is derived from these: label becomes the title, position the order. Always write collapsed: true — otherwise the sidebar opens as one long expanded list |
Utility sections listed in ui.navCategories.exclude | Changelog, writing conventions and the publishing handbook belong in the sidebar; occupying the navbar pushes real content sections behind. List directory names, not labels |
| Seven required frontmatter fields on every doc | title / description / sidebar_position / tags / subject_version / updated / access; missing one aborts validation |
i18n/<locale>/ mirroring docs/ | Every doc needs a translation, or the coverage check fails |
| Changelog generated, never hand-written | Yearly files under docs/changelog/ are rewritten wholesale by npm run changelog |
3. Verify in this order
npm run check # frontmatter + architecture guard
npm run check:i18n # translation coverage and residual Chinese
npm run changelog # rebuild yearly files from the new content
npm run build # real build
Those four in sequence are exactly npm run verify, which is what CI runs.
4. The four pitfalls that bite first
The second navbar row only recognises top-level directories under docs/. Promote a sub-category (e.g. docs/engine/memory/) to a section and the navbar gets an item that 404s. New section = new top-level directory.
The reverse is explicit: a top-level directory you do not want in the navbar must be listed in ui.navCategories.exclude: ['changelog']. Forget it and the item appears — that is the price, and the convenience, of zero-config sections.
subject.versions is a whitelist: a doc whose subject_version is not in it fails validation. Change both together, otherwise the very first doc gets rejected.
A tag that is not in tagGroups raises no error, but subscriptions and sidebar filtering silently drop it. This never surfaces at build time — readers just stop receiving updates.
static/ is copied verbatim into public files. Gated bodies and attachments (access other than free) must never go there. The architecture guard blocks it, but don't wait to be blocked.