Repository navigation
docs: fix broken links in learning/ and add a docs link check (OPS-71) - #45
Merged
Merged
Conversation
Links to the in-app quickstart and hosted quickstart pointed at site paths that do not exist (/sdk-auth/sdk-quickstart/, /quickstart/hosted-quickstart/), and usage limits sent readers to the How Bridge works overview instead of the React page. They are now relative .md links, which the docs sync rewrites to the React pages. Refs: OPS-71
…sync and before push (OPS-71) scripts/check-docs-links.mjs (dependency-free node, about 0.05 s) checks every link in learning/ the way the docs sync publishes it to thebridge.dev/docs: relative .md links must point at an existing file and heading, and must be a form the sync rewrites to that file's own page; site paths like /auth/config/ must be real docs pages (scripts/docs-site-pages.txt, plus the pages this repo's own learning/ produces); #anchors must match a heading; two files must not publish to the same page. It runs in three places: - the Docs links workflow, on pull requests to main that touch learning/ or the checker (separate from build, test and publish); - the Sync Docs workflow, before the sync, so a broken link never reaches the website; - before push, via .githooks/pre-push, when a pushed commit touches learning/. Opt in per checkout with: git config workflows.localPrePush .githooks/pre-push Refs: OPS-71
iman-nebulr
changed the title
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.
Fixes links in
learning/that 404 or land on the wrong page on thebridge.dev/docs (OPS-71). They were fixed earlier only in the site's synced copy, so the next docs sync would have broken them again; this fixes them at the source.mechanisms.md:297:(/quickstart/hosted-quickstart/)to(quickstart/hosted-quickstart.md),(/sdk-auth/sdk-quickstart/)to(sdk-auth/sdk-quickstart.md)(both 404 today)auth/ui/email-password.md:14:(/sdk-auth/sdk-quickstart/)to(../../sdk-auth/sdk-quickstart.md)(404 today)billing/limits/usage-limits.md:23:(/mechanisms/)(the all-framework overview) to(../../mechanisms.md)(the React page)Relative
.mdlinks are the form the docs sync rewrites to this framework's own page; hard-coded site paths are not checked against the site.Merge order: the
../mechanisms.mdand../../mechanisms.mdlinks need the site change in bridge-web MR !30 (the sync maps a link to a top-level doc to its own page, /docs/mechanisms//). Merge that first. Before it, these links would land on the linking page's own section (wrong page, not a 404).Merging to main triggers the docs sync to the website. Not merged by the author.
Refs: OPS-71
Docs link check (approved by the owner)
scripts/check-docs-links.mjs: dependency-free node, about 0.05 s. It checks every link inlearning/the way the docs sync publishes it to thebridge.dev/docs:.mdlinks: the file exists, any#anchormatches a heading, and the link is a form the sync rewrites to that file's own page (the sync cannot rewrite a link naming two or more folders);/auth/config/,/docs/...): a real docs page, fromscripts/docs-site-pages.txt(regenerate with--print-site-pages <bridge-web>/bridge-docs/src/content/docs) plus the pages this repo's ownlearning/produces;#anchorson the same page, and two files publishing to the same page.README.md files are skipped (the sync does not publish them).
Where it runs:
.github/workflows/docs-links.yml: pull requests to main touchinglearning/or the checker. A separate workflow; build, test and publish jobs are unchanged.sync-docs-only.yml: a step before the sync, so a broken link stops the sync instead of reaching the website..githooks/pre-push, through the shared hook's opt-in (git config workflows.localPrePush .githooks/pre-push; undo withgit config --unset workflows.localPrePush). Runs only when a pushed commit toucheslearning/or the checker, and checks the pushed commit, not the working tree. Skip once:SKIP_LINK_CHECK=1 git push.node scripts/check-docs-links.mjs(orcheck:docs-linksin package.json).