Set up deterministic GitBook-driven docs deployment - #20
Merged
Conversation
...with build-time sync and no content churn in repo. - Added build-time GitBook sync pipeline in apps/docs/scripts/sync-gitbook.mjs to clone pinned content, transform GitBook markdown syntax, copy assets, generate sidebar, and emit manifest. - Runtime/build to generated navigation and sync-first flow: - apps/docs/astro.config.mjs now uses generated sidebar and disables default Starlight 404 route. - apps/docs/package.json now has sync:content, dev:sync, and sync-before-build behavior, with plain dev for fast local iteration. - Added safety/consistency controls: - Overwrite guard via GITBOOK_ALLOW_OVERWRITE=1. - Frontmatter title injection when missing. - Duplicate H1 removal when it matches frontmatter title. - Sidebar generation cleanup to avoid duplicate parent-as-child labels and prefer Overview. - Introduced pinned source-of-truth lock file: - Added apps/docs/gitbook.lock.json with GitBook repo + ref SHA. - Sync script now defaults to lock file repo/ref (env overrides still supported), including SHA checkout support. - Generated-artifact model: - Added apps/docs/.gitignore entries for synced docs content/assets and generated sidebar/manifest so content syncs are local/build artifacts. - Removed manual tracked sidebar and updated tests to validate generated sidebar (apps/docs/src/config/sidebar.test.ts; deleted apps/docs/src/config/sidebar.ts). - Added scheduled auto-sync CI in bdc-web: - New workflow .github/workflows/docs-gitbook-sync.yml checks GitBook main every 30 minutes (plus manual trigger), updates lock when changed, validates docs build, and commits only lock updates on success. - Trigger on schedule-only and workflow_dispatch only. etc. - avoid node 20 - organize imports and formatting - shift action timing - add docs site readme
mbwatson
force-pushed
the
feature/docs-build-sync
branch
from
August 5, 2026 17:14
ce1ff6f to
377ac33
Compare
mbwatson
marked this pull request as ready for review
August 5, 2026 19:10
Amaru333
approved these changes
Aug 12, 2026
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
2 participants
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.
...with build-time sync and no content churn in this repo.
Added build-time GitBook sync pipeline in
apps/docs/scripts/sync-gitbook.mjsto clone pinned content, transform GitBook markdown syntax, copy assets, generate sidebar, and emit manifest.Runtime/build to generated navigation and sync-first flow:
apps/docs/astro.config.mjsnow uses generated sidebar and disables default Starlight 404 route.apps/docs/package.jsonnow hassync:content,dev:sync, and sync-before-build behavior, with plaindevfor fast local iteration.Added safety/consistency controls:
GITBOOK_ALLOW_OVERWRITE=1.title.Overview.Introduced pinned source-of-truth lock file:
apps/docs/gitbook.lock.jsonwith GitBook repo + ref SHA.Generated-artifact model:
apps/docs/.gitignoreentries for synced docs content/assets and generated sidebar/manifest so content syncs are local/build artifacts.apps/docs/src/config/sidebar.test.ts; deletedapps/docs/src/config/sidebar.ts).Added scheduled auto-sync CI in bdc-web:
.github/workflows/docs-gitbook-sync.ymlchecks GitBookmainevery 30 minutes (plus manual trigger), updates lock when changed, validates docs build, and commits only lock updates on success.workflow_dispatchonly.