Repository navigation
feat: single-source config docs generated from YAML seeds (#2107) - #2114
Merged
Merged
Conversation
6 tasks
website/config-reference/*.yaml (7 domain files, 225 entries) become the ONLY hand-maintained config reference. tools/gen-config-docs.mjs (pure Node, zero deps) regenerates, inside <!-- bili:gen --> / /* bili:gen */ marker blocks: the Parameter Reference index + env-knob map tables in CONFIGURATION.md/.zh-CN.md, and the i18n dict segments in website/main.js plus the table rows in website/docs/index.html (with inline EN no-JS fallback). Generated artifacts are committed; pages.yml untouched (site stays static, zero build step). CI gains two guard jobs: docs-sync (regenerate + git diff --exit-code on the four artifact files) and docs-coverage (every BILI_*/ACP_* env var read in src/ and every FileConfig top-level key must have a seed entry; missing names listed, exit 1). Acceptance verified locally: double-run byte-identical; wrong default -> readable diff; deleted env entry -> coverage red naming it; EN/ZH dict sets equal with all refs resolving; subpath mount serves all local assets 200. Behavior changes (docs-only, no config surface added): env-map table rows now sorted by env name (was subsystem-grouped) and zh defaults normalized to the shared value strings; cr.models/cr.compat site cells switch data-i18n -> data-i18n-html because their values contain <span class='mech'> markup that previously rendered as raw text; Parameter Reference section gains its first content (previously an empty legend stub); human prose outside marker blocks is byte-untouched.
ranxianglei
force-pushed
the
2026-10-04_config-docs-gen
branch
from
October 4, 2026 15:39
5e26b95 to
19bb01a
Compare
Contributor
📦 Built Package ArtifactBranch: Option A — Install this exact build (recommended)npm install -g billion-context@0.0.2162-pr.2114.d4143a4This exact version is immutable and reproducible. The rolling Option B — Download artifact
tar xzf billion-context-pr2114.tgz
npm install -g packageInstall instructions are refreshed on each push. |
Contributor
📦 Merged Build PublishedThis merge to master was published as npm install -g billion-context@0.0.23-master.5e43209 # this exact build
npm install -g billion-context@master # always the newest merged build
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #2107
What
#2052's audit exposed the structural gap: website /docs/ config references were hand-transcribed snapshots with no pipeline to src/ + CONFIGURATION.md. This PR makes the config docs a single source of truth — humans write one place, both artifacts (repo manual + site) stay consistent, drift is blocked at PR merge time.
Generated artifacts are committed inside
<!-- bili:gen id -->//* bili:gen */marker blocks; human prose outside blocks is byte-untouched. Site stays pure static — pages.yml untouched, no build step added.Drift guards (two new jobs in existing ci.yml)
git diff --exit-codeon the four artifact files — schema edited without re-running the generator goes red.BILI_*/ACP_*env var read in src/ (direct reads, bracket reads, alias-param reads, helper-call literals incl. second-arg forms) and every FileConfig top-level key must have a seed entry — undocumented param goes red with the missing names listed.Acceptance evidence (all verified locally on the committed state)
generate)Behavior changes (docs-only; NO config surface added, no runtime change)
<span class='mech'>markup that previously rendered as RAW TEXT in the browser (pre-existing defect, fixed mechanically by the generator).Note on an in-passing fix (#2064 shipped it first)
While working this I found
releaseNotesCheck/releaseNotesUrldeclared in FileConfig and read by loadOptions but missing from KNOWN_TOP_LEVEL_KEYS — users setting either got a spurious "ignoring unknown top-level config key" warning although the value applied. I committed the one-line Set fix; after rebasing onto current master it became a no-op because #2064 had already added both keys to the Set (the rebase dropped my duplicate commit). The branch therefore carries only the docs-generation commit; nothing further needed on that front.