Follow-up to #2546, which fixes absolute /docs/... links on the single Tier 1 Orgs page. That fix treats one symptom; this issue makes the fix stick repo-wide.
Background
Internal doc links should use relative ../path/file.mdx syntax with the file extension (Docusaurus docs), a convention already codified in docs/platforms/anchor-platform/CONTRIBUTING.md.
Why the existing CI doesn't catch this: the pull_request workflow (main.yml) runs two relevant jobs, and neither flags absolute-but-valid internal links:
mdx-format → pnpm ci:mdx is prettier — it checks formatting, not link style. /docs/foo and ../foo.mdx are equally "formatted."build → pnpm build with onBrokenLinks: "throw" only fails on dead routes. An absolute /docs/... link that resolves to a valid page is not broken, so it passes.
Result: absolute internal links pointing at pages that exist sail through CI today. There are currently ~22 occurrences across 7 files (grep -rn '](/docs' docs/).
Sub-tasks
The CI gate is the real gate; the pre-commit hook is a fast-feedback convenience layered on top.
Scope note
Limit the check to ](/docs specifically for now. There are ~155 bare root-relative ](/...) links (non-docs, e.g. lab slugs) that may be intentional and need separate evaluation.
Follow-up to #2546, which fixes absolute
/docs/...links on the single Tier 1 Orgs page. That fix treats one symptom; this issue makes the fix stick repo-wide.Background
Internal doc links should use relative
../path/file.mdxsyntax with the file extension (Docusaurus docs), a convention already codified indocs/platforms/anchor-platform/CONTRIBUTING.md.Why the existing CI doesn't catch this: the
pull_requestworkflow (main.yml) runs two relevant jobs, and neither flags absolute-but-valid internal links:mdx-format→pnpm ci:mdxis prettier — it checks formatting, not link style./docs/fooand../foo.mdxare equally "formatted."build→pnpm buildwithonBrokenLinks: "throw"only fails on dead routes. An absolute/docs/...link that resolves to a valid page is not broken, so it passes.Result: absolute internal links pointing at pages that exist sail through CI today. There are currently ~22 occurrences across 7 files (
grep -rn '](/docs' docs/).Sub-tasks
](/docs...)links to relative.mdxlinks in the other 6 files (Tier 1 Orgs handled in Link to MDX files on Tier 1 Orgs page #2546):docs/validators/README.mdx,docs/validators/admin-guide/configuring.mdx,docs/validators/admin-guide/prerequisites.mdx,docs/validators/admin-guide/publishing-history-archives.mdx,docs/tools/lab/transaction-dashboard.mdx,docs/platforms/anchor-platform/CONTRIBUTING.md. Preserve any#anchors.mdx-formatjob ofmain.ymlthat fails ifgrep -rn '](/docs' docs/finds anything. Unbypassable, setup-independent — this is the guarantee..husky/pre-commithook, so contributors with the repo set up catch it before the slow CI round-trip. Scoped to staged files so pre-existing debt in untouched files never blocks unrelated commits.The CI gate is the real gate; the pre-commit hook is a fast-feedback convenience layered on top.
Scope note
Limit the check to
](/docsspecifically for now. There are ~155 bare root-relative](/...)links (non-docs, e.g. lab slugs) that may be intentional and need separate evaluation.