feat(docs): add offline link and accessibility checks for the public site - #18
Open
dchaudhari7177 wants to merge 1 commit into
Open
dchaudhari7177 wants to merge 1 commit into
dchaudhari7177 wants to merge 1 commit into
Conversation
…site Covers both surfaces in one pass: the Markdown under docs/open-source and the static site in docs/open-source/site. Broken internal links, link text that says nothing read out of context, and four page-level regressions a documentation edit can plausibly cause -- exactly one main landmark, a non-empty title, a lang on <html>, an alt on every image. Deterministic and offline by construction. External URLs, mailto: links and same-page anchors are deliberately not resolved: a gate that needs the network fails for reasons unrelated to the change under review. Wired into public-docs.yml before the site is assembled, so a broken link stops the deploy rather than shipping. Runs clean on the current tree -- 11 markdown files and 1 page.
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.
Closes #6
npm run docs:public:check— one pass over both surfaces, offline.Clean on the current tree:
What it checks
Links — every internal
[text](path)and<a href>indocs/open-source/**.mdanddocs/open-source/site/*.htmlmust resolve to a file that exists.Link text — a label from a small closed set (
click here,here,read more, …) is rejected. Someone tabbing a page hears the links out of context, so three "click here"s are three identical destinations as far as they can tell.Page accessibility — four rules, each a regression a documentation edit can plausibly cause and each decidable from the markup: exactly one
mainlandmark, a non-empty<title>, alangon<html>, and analton every image.Determinism, which is the constraint that shaped it
External URLs,
mailto:, protocol-relative and same-page anchors are deliberately not resolved. Fetching them is the obvious way to write a link checker and the reason most of them get disabled: a gate that needs the network fails for reasons unrelated to the change under review. Every rule here is answered from files in the checkout, so the same tree gives the same verdict anywhere. There is a test asserting that.The rules live in
scripts/lib/saferide-public-docs.mjsreturning findings, with a thin CLI inscripts/saferide-public-docs-check.mjs— matching thelib/+ entry-point split the other validators use, and letting the tests call the rules directly.Acceptance criteria
docs/open-sourceand the static sitealtscripts/__tests__/fixtures/public-docs/{passing,failing}/docs/open-source/build-and-test.mdThe fixtures
The failing one breaks every rule exactly once, and the test asserts each message individually rather than just counting — so a fixture edit that quietly disables a rule fails the suite instead of reducing coverage silently:
13 tests. Beyond the two fixtures they cover the exclusions individually (external,
mailto:, protocol-relative, same-page anchor, fragment-on-a-real-file), that a repeated broken target is reported once per file rather than once per occurrence, that trailing punctuation does not hidehere., thatsite/is not walked as Markdown, and that the realdocs/open-source/passes — a gate that does not hold on the tree it is added to is not a gate.CI
Added to
public-docs.ymlbefore the site is assembled, so a broken link stops the deploy rather than shipping.actions/setup-nodeis SHA-pinned to match the existing steps in that file.Verification
npm run docs:public:check— check clean, 13 tests pass. Also ran the CLI against both fixtures directly via--root, which is how I confirmed the failing one exits 1.