How this site is built

The site lives on the gh-pages branch; the engine lives on master. The pipeline reads master and writes gh-pages. Neither branch contains the other.

Generated or hand-written

Never edit these by hand. They are rewritten wholesale:

• _data/cvars.json, _data/commands.json, _data/reference-meta.json, and _data/reference_stats.json
• reference.md, reference/cvars/*.md, reference/commands/*.md
• reference/{all,audit,sources,removed}.md, the reference/{categories,features,modules,origins}.md index pages, and the collections under each of those directories
• features/whats-new.md, features/emoji.md, the images under assets/emoji/, and the JSON under assets/data/
• tools/cvar_audit/baseline-totals.json, written by validate.py --update-baseline-totals
• index.md: the homepage is generated too, which catches people out

assets/data/config-generator.json is generated separately, by tools/config_generator/build.py from the Docker configs and the JSON beside that script.

Everything else is hand-written: the guides, the Features pages, this page. check_generated.py catches some hand edits: it fails if the homepage, the JSON under assets/data/ or reference_stats.json no longer match the data, or if a generated page is missing. It does not compare the text of the other generated pages, so an edit to one of those passes the checks and is silently thrown away at the next regeneration.

Hand-written pages that quote a count from the reference read it from _data/reference_stats.json instead of typing it, so the figure changes when the reference does.

The pipeline

Six scripts, each doing one thing, under tools/cvar_audit/:

Two data files steer the result by hand: overrides.json corrects individual fields where the source cannot be read correctly, and removed.json records entries intentionally dropped.

Regenerating

From the repository root, in this order:

python3 tools/cvar_audit/provenance.py --pr-json <page-1.json> --pr-json <page-2.json>
python3 tools/cvar_audit/build_reference.py
python3 tools/cvar_audit/runtime_check.py --cvars <cvarlist.txt> --commands <cmdlist.txt> --build <BUILD_ID>
python3 tools/cvar_audit/generate_docs.py
python3 tools/cvar_audit/validate.py --update-baseline-totals
python3 tools/config_generator/build.py

The last two record the new baseline totals and rebuild the config generator’s data, which lists only cvars the reference knows about. Skip them and run_all.sh fails.

provenance.py expects remote-tracking refs for every upstream: origin/master, openjk/master, eternaljk/master, japro/main, jk2mv/master, newjk/master, somaz/rend2-unified-wip, and Sunny/master, plus PR metadata as JSON. runtime_check.py needs console output captured from a client you actually launched.

The static part is automated; the runtime part is not. reference-check.yml on master fetches every upstream, collects the PR metadata, reruns provenance, reference assembly and page generation, runs every check and a Jekyll build, and opens or updates a pull request against gh-pages. It runs weekly, when a release is published, and after each automatic latest-build release. Nothing is pushed to the published branch without review.

It keeps the existing runtime reconciliation instead of redoing it, because no runner launches the game, and an old +cvarlist capture must not be relabelled as current. A person with a real capture still runs runtime_check.py by hand.

Between refreshes, check_drift.py compares the registrations at a source ref against the checked-in data and fails when they diverge. tools/cvar_audit/README.md is the full contract.

A refresh moves the reference to a new source commit, but hand-written guides keep citing the commit they were checked against. Their blame links stay valid; the prose is only as current as that check. When you re-verify a guide, re-pin its links to source_commit.

Verifying a change

One script runs every check except the Jekyll build and the feed check, and keeps going after a failure so one run reports every problem:

tools/cvar_audit/run_all.sh

The site also builds locally, which is the only way to check anything that depends on rendering, including Liquid templates, the search index, or how Markdown inside an HTML block is parsed:

bundle install
bundle exec jekyll build

Pushing to gh-pages runs the deploy workflow, .github/workflows/pages.yml, which builds with the same Gemfile, so a local build matches production. Before building, it runs page_dates.py to record each page’s last-changed date from git, which is why that date needs no upkeep. A local preview shows no dates unless you run python3 tools/cvar_audit/page_dates.py first.

Adding a page

Create a Markdown file, give it front matter per CONVENTIONS.md, and place it in a section.

The header tabs are hardcoded in _layouts/reference.html; there is no theme. A page joins a section through its parent (the section page’s title) and nav_order, which give it a breadcrumb, previous/next links, and the section’s highlighted header tab. Also add a card for it to _data/navigation.yml, which draws the Install, Server hosting, Features, Development and Help hubs. Only a new top-level section means editing the layout. Add hand-written pages to the list in check_generated.py too, or their internal links are never validated.

Everything else is automatic: the page is picked up by the site search through search-index.json, and its headings become linkable anchors.

What the site is built with

No theme and no plugins. Jekyll renders Markdown through kramdown; the layouts, the CSS and the three JavaScript files are all local and hand-written. The search index and the Atom feed are Liquid templates rather than plugins, so they cannot break when an upstream gem changes.

Last changed 24 October 2026 History Edit this page on GitHub