Skip to main content
Version: Next

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.

FieldWhat to set
siteIdNamespace for the new site (subscription tag prefix, search index, entitlement table are all scoped by it)
title / tagline / navbarTitle / footerTextSite identity
content.root / content.topicSlugContent directory and section slug
subject.field / labelZh / labelEn / versions / publishedVersions / defaultVersionThe dimension that varies per subject: engine version, edition, school, dynasty
tagGroupsTag groups for subscriptions and filtering
changelog.kinds / labelsChangelog category words and field names
llms.title / description / notes / preferredPathsSite summary and starting points for llms.txt
search.indexPrefixSearch index ownership
ui.*Interface copy, always as {zh, en} pairs

2. What the content pack must contain​

RequiredWhy
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 directoryThe 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.excludeChangelog, 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 doctitle / 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-writtenYearly 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​

A section at the wrong level

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.

Mismatched tier values

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.

Tags outside tagGroups

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.

Gated content inside static/

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.