Migrate docs to VitePress, add Bun/TypeScript book pipeline, harden CI - #1134
Merged
Conversation
Replace MkDocs with VitePress for docs.plurality.net (docs/.vitepress/,
docs/public/ including CNAME, corrected contributor-guide asset paths).
Delete mkdocs.yml and the old docs-ci.yml workflow.
Add a Bun/TypeScript manuscript compiler (scripts/book/) with typed
publication-manifest generation and PDF/EPUB validation, alongside the
existing Docker/Pandoc/XeLaTeX legacy renderer, which remains the
production PDF/EPUB baseline. Add a non-public Vivliostyle candidate
renderer/pilot (publication/) that does not gate release.
Consolidate CI into a single .github/workflows/main.yml job graph:
verify -> {docs, manifest}; manifest -> {legacy, candidate};
legacy -> legacy-validation; candidate -> candidate-validation;
docs -> deploy-pages; legacy-validation + docs -> release;
release + deploy-pages -> webhook. Release, Pages deploy, and the
rebuild webhook only fire on push to pluralitybook/main; candidate
render/validation never gates them. Actions pinned to commit SHAs.
Fix false-green test gate: package.json `check` ran Bun's built-in
`bun test` instead of the Vitest suite; now `bun run typecheck &&
bun run test`. Bump vitest to 4.1.10 to match vite-plus's runtime API.
Replace a nonfunctional filesystem-mtime freshness check (artifact
extraction always sets download-time mtimes, making it a permanent
no-op) with an explicit manifest.sourceRevision == EXPECTED_SOURCE_REVISION
guard, set from ${{ github.sha }} in both validation jobs.
Fix XeLaTeX Unicode ellipsis handling in scripts/xelatex-preamble.tex.
Remove two stale 2023 editorial *.backup files superseded by their
current contents/english/ chapters; git history retains their content.
29/29 tests pass; bun run check, bun run docs:build, and a full
Vivliostyle candidate render+validate (both locales) were exercised
locally with a fixed BOOK_DATE. Real Docker/Pandoc/XeLaTeX legacy
render was not run locally (heavy/networked); its orchestration is
covered by unit tests and will run in CI.
GitHub Pages source must be switched from the gh-pages branch to
"GitHub Actions" only after this workflow is green on main.
…o vp run tasks Task 1: vp install --frozen-lockfile failed in CI with "error: Package manager bun@1.4.0 not found on https://registry.npmjs.org/@oven/bun-linux-x64/-/bun-linux-x64-1.4.0.tgz". package.json's packageManager field pinned bun@1.4.0, a version that does not exist on the npm registry mirror vp uses to fetch a pinned package manager (latest published there is 1.3.14). The bun.lock lockfileVersion (1) only requires bun >= 1.2, so pin packageManager to bun@1.3.14 instead. Reproduced the exact failure locally with the same vp 0.2.4 binary and confirmed the fix resolves it. Task 2: collapse the two parallel invocation paths (package.json scripts run via `bun run`, and a handful of vite.config.ts `tasks` that just re-wrapped those scripts via `bun run`) into one entrypoint. vite.config.ts `run.tasks` is now the single source of truth for all 17 project commands (typecheck, test, check, docs:dev/build/preview, book:assemble, book:manifest, book:candidate:prepare/en/zh-TW/all/validate, book:legacy:en/zh-TW/all/validate), each command copied verbatim from the former package.json scripts. package.json's `scripts` block is removed entirely (vp itself now rejects a task/script name collision, confirming vp run tasks alone are sufficient in this pinned CI environment). .github/workflows/main.yml now invokes every task exclusively via `vp run <task>` (including bare `bun scripts/book/*.ts <locale>` calls, replaced with matrix-driven `vp run book:candidate:${{ matrix.locale }}` / `book:legacy:${{ matrix.locale }}`). Task caching is disabled at the run level since these commands depend on untracked env vars (BOOK_DATE, OUTPUT_ROOT, SOURCE_REVISION, etc.) and must always execute, matching prior behavior exactly. No changes to Docker/Pandoc/XeLaTeX legacy renderer internals, the release-gating graph, or the EXPECTED_SOURCE_REVISION guard.
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
1 participant
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.
Replace MkDocs with VitePress for docs.plurality.net (docs/.vitepress/,
docs/public/ including CNAME, corrected contributor-guide asset paths).
Delete mkdocs.yml and the old docs-ci.yml workflow.
Add a Bun/TypeScript manuscript compiler (scripts/book/) with typed
publication-manifest generation and PDF/EPUB validation, alongside the
existing Docker/Pandoc/XeLaTeX legacy renderer, which remains the
production PDF/EPUB baseline. Add a non-public Vivliostyle candidate
renderer/pilot (publication/) that does not gate release.
Consolidate CI into a single .github/workflows/main.yml job graph:
verify -> {docs, manifest}; manifest -> {legacy, candidate};
legacy -> legacy-validation; candidate -> candidate-validation;
docs -> deploy-pages; legacy-validation + docs -> release;
release + deploy-pages -> webhook. Release, Pages deploy, and the
rebuild webhook only fire on push to pluralitybook/main; candidate
render/validation never gates them. Actions pinned to commit SHAs.
Fix false-green test gate: package.json
checkran Bun's built-inbun testinstead of the Vitest suite; nowbun run typecheck && bun run test. Bump vitest to 4.1.10 to match vite-plus's runtime API.Replace a nonfunctional filesystem-mtime freshness check (artifact
extraction always sets download-time mtimes, making it a permanent
no-op) with an explicit manifest.sourceRevision == EXPECTED_SOURCE_REVISION
guard, set from ${{ github.sha }} in both validation jobs.
Fix XeLaTeX Unicode ellipsis handling in scripts/xelatex-preamble.tex.
Remove two stale 2023 editorial *.backup files superseded by their
current contents/english/ chapters; git history retains their content.
29/29 tests pass; bun run check, bun run docs:build, and a full
Vivliostyle candidate render+validate (both locales) were exercised
locally with a fixed BOOK_DATE. Real Docker/Pandoc/XeLaTeX legacy
render was not run locally (heavy/networked); its orchestration is
covered by unit tests and will run in CI.
GitHub Pages source must be switched from the gh-pages branch to
"GitHub Actions" only after this workflow is green on main.