fix(docs): repair broken links in app-shell migrations - #219
Merged
Conversation
The PR Checks workflow has been failing on main, and so on every open dependency PR: - `lint`: the VitePress build failed on two dead links to ../packages/core/CHANGELOG. That path is correct inside the app-shell repo, but docs-sync copies the file to app-shell/changelog.md, so the original path resolves to nothing here. - `schema-check`: two anchors in docs/app-shell/migrations.md were written with GitHub's slugger, which emits a hyphen per separator character, so " / " and " -> " produced a doubled hyphen. mdschema collapses runs of hyphens and saw both links as broken. docs/app-shell is regenerated wholesale by the nightly docs-sync run, so fixing the file alone would revert within a day. Both rewrites are added to the sync post-processing, and the changelog rewrite is derived from the `extraCopies` list rather than hardcoding the path, so the copy rule and the link rule cannot drift apart. Running `pnpm sync:app-shell` reproduces the committed file exactly. A third slug dialect is left alone deliberately: VitePress renders `## 1.12.0: ...` as `id="_1-12-0-..."`, so the 9 anchors in the migrations table scroll nowhere on the site. The build does not check fragments, so nothing catches it. Emitting VitePress's dialect and moving the anchor check out of mdschema was tried and reverted as more machinery than the problem warrants; the reasoning is recorded next to collapseAnchorHyphens.
jackchuka
marked this pull request as ready for review
August 25, 2026 03:49
anukiransolur
approved these changes
Aug 25, 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.
PR Checkshas been failing onmain, and therefore on every open dependency PR in this repo (7 of them). Two independent problems, both indocs/app-shell/migrations.md.lintThe VitePress build failed on two dead links to
../packages/core/CHANGELOG(lines 10 and 161 — hence "2 dead link(s) found"). That path is correct inside the app-shell repo, butdocs-synccopies the file here asapp-shell/changelog.md, so the original path resolves to nothing.schema-checkTwo anchors were written with GitHub's slugger, which emits a hyphen per separator character, so
" / "and" → "produced a doubled hyphen. mdschema collapses runs of hyphens and saw both links as broken.Why the fix is in the sync script
docs/app-shellis regenerated wholesale by the nightlydocs-syncrun (rm -rf+ re-copy, 00:00 UTC), so fixing the file alone would revert within a day and the deploy would break again. Both rewrites are added to the sync post-processing.The changelog rewrite is derived from the
extraCopieslist rather than hardcoding the path, so the copy rule and the link rule cannot drift apart.Verification
pnpm sync:app-shellrun against a local app-shell checkout reproduces the committed file exactly — the next nightly sync is a no-op, not a revert.typecheck,docs-sync typecheck,lint,fmt:check,check:links,schema-checkandbuildall pass locally.Known limitation, deliberately not fixed
A third slug dialect is left alone. VitePress renders
## 1.12.0: ...asid="_1-12-0-...", so the 9 anchors in the migrations table scroll nowhere on the site — that is the pre-existing state, and the build does not check fragments so nothing catches it.Emitting VitePress's dialect and moving the anchor check out of mdschema was implemented and then reverted: measured across the corpus it was a no-op for all 142 SDK anchors, so ~90 lines of slugger, rewrite and checker were earning their keep on a single file. The reasoning is recorded next to
collapseAnchorHyphensfor whoever picks it up.