ci: enforce relative internal doc links + pre-commit hint#2550
Open
ElliotFriend wants to merge 7 commits into
Open
ci: enforce relative internal doc links + pre-commit hint#2550ElliotFriend wants to merge 7 commits into
ElliotFriend wants to merge 7 commits into
Conversation
Replace absolute /docs/... links with relative ../path/file.mdx links per Docusaurus convention (docs/platforms/anchor-platform/CONTRIBUTING.md). Relative links with the file extension are validated at build time by onBrokenMarkdownLinks, unlike absolute route links. Fixes stellar#2546 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Sweeps the remaining absolute /docs/... links (7 occurrences across 5 files) to relative ../path/file.mdx links per the repo convention. Relative links with the file extension are validated at build time by onBrokenMarkdownLinks; absolute route links are not. Tier 1 Orgs page is handled separately in stellar#2546. CONTRIBUTING.md is left untouched: it is excluded from the docs build and its /docs link is an intentional illustrative example. Part of stellar#2547 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
…s-sweep-2547' into chore/enforce-relative-links-2547
Sub-task 2 of stellar#2547. Adds two layers preventing absolute /docs/... links from regressing: - CI gate (main.yml): repo-wide grep in the mdx-format job, fails the PR if any docs/ .md/.mdx file contains a `](/docs` link. Unbypassable, setup-independent — the real guarantee. - Pre-commit hint (.husky/pre-commit): staged-files-only grep for fast local feedback. Scoped to staged files so pre-existing links in untouched files never block unrelated commits. Both exclude CONTRIBUTING.md, which is not part of the docs build and whose /docs link is an intentional illustrative example. Part of stellar#2547 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR advances the repo-wide convention of using relative .mdx internal doc links (instead of absolute /docs/... routes) by adding an enforcement check in CI and a fast-feedback check in the pre-commit hook, alongside the stacked link-conversion edits in docs.
Changes:
- Convert remaining
/docs/...internal links to relative.//../.mdxlinks in several docs pages (stacked on earlier PRs). - Add a CI gate in
mdx-formatto fail PRs if any](/docslinks exist underdocs/(excludingCONTRIBUTING.md). - Add a staged-files-only pre-commit check to warn early about absolute
/docslinks in edited docs files.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
docs/validators/tier-1-orgs.mdx |
Replaces absolute /docs/... links with relative .mdx links for validator docs. |
docs/validators/README.mdx |
Updates Tier 1 Organizations link to a relative .mdx target. |
docs/validators/admin-guide/publishing-history-archives.mdx |
Updates Tier 1 Organizations link to relative .mdx. |
docs/validators/admin-guide/prerequisites.mdx |
Updates Tier 1 + reserve requirements + history-archives links to relative .mdx. |
docs/validators/admin-guide/configuring.mdx |
Updates Tier 1 + publishing-history-archives links to relative .mdx. |
docs/tools/lab/transaction-dashboard.mdx |
Updates Indexers and Block Explorers links to relative .mdx targets. |
.husky/pre-commit |
Adds a staged-docs-only grep to catch ](/docs links locally before CI. |
.github/workflows/main.yml |
Adds CI step to fail when absolute internal /docs links are present in docs/. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
Preview is available here: |
…orce-relative-links-2547
|
Preview is available here: |
wmendes
approved these changes
Jul 14, 2026
kaankacar
approved these changes
Jul 14, 2026
…orce-relative-links-2547
Replace the repo-wide grep with a single canonical script (scripts/check-relative-links.sh) shared by CI and the pre-commit hook, mirroring how `pnpm format:mdx` avoids duplicated prettier invocations. The check now inspects a word-level diff (git diff --word-diff=porcelain) and flags absolute /docs links only in newly proposed content — added tokens. Fixing a typo on a line that already contains an absolute link no longer blocks the commit; only introducing or editing a /docs link does. Contributors are never punished for pre-existing debt in untouched lines. - scripts/check-relative-links.sh: --staged (pre-commit) and --range (CI) - main.yml: fetch-depth 0 so the PR base is available to diff against - package.json: add `check:links` alias Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Contributor
Author
|
made an update here so that
|
|
Preview is available here: |
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
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.
Sub-task 2 (final piece) of #2547. Adds automation so absolute
/docs/...internal links can't regress after the manual fixes in #2548 and #2549.Two layers
1. CI gate — the guarantee. A step in the
mdx-formatjob ofmain.ymlgrepsdocs/for](/docsand fails the PR if any are found. Unbypassable and setup-independent, so it catches links regardless of contributor tooling or GitHub web edits.2. Pre-commit hint — the ergonomics. A staged-files-only grep appended to
.husky/pre-commit, giving fast local feedback before the (minutes-long) CI round-trip. Scoped to staged files so pre-existing links in untouched files never block unrelated commits — CI is the repo-wide backstop.Why two layers: the hook is bypassable (
--no-verify) and only runs for contributors with the repo set up, so it can't be the guarantee — but it saves the 90% who do have it set up a slow failed-CI cycle. See the discussion in #2547.Both exclude
CONTRIBUTING.md: it'sexcluded from the docs build (docusaurus.config.ts line 143) and its/docslink is a deliberate illustrative example.Why the naive check isn't enough on its own
The existing PR checks don't catch this class:
ci:mdxis prettier (ignores link style), andpnpm buildwithonBrokenLinks: "throw"only fails on dead routes — an absolute link to a page that exists passes. This grep closes that gap.This branch is stacked on #2548 and #2549 so its own CI passes on a clean tree. Merge those two first. Once they land, this PR's diff reduces to just the two infra files (
main.yml,.husky/pre-commit). If merged before them, the repo-wide gate will (correctly) fail on the not-yet-converted links.Verification (all run locally)
](/docs; ignores CONTRIBUTING.md/docslink; passes a clean docs file; passes a stagedCONTRIBUTING.mdwith a/docslinkset -e-safe (husky runssh -e): the staged-file substitution is guarded with|| true, and the empty-stage path (no docs staged) skips cleanlyCloses #2547
🤖 Generated with Claude Code