Check the cross-repository links the Markdown standard tells authors to write

[MariusStorhaug]

Context and request

Markdown.md tells authors: "Prefer relative links within a repository; use the canonical published URL for cross-repository references." Test-DocumentationLink.ps1 then ignores external links on purpose. The one link form the standard actively asks for is the one form nothing verifies.

The checked case is the easy one. A relative link points at a file on disk, in the same commit, changed by the same pull request. A cross-repository link points at something that moves on someone else's schedule, without anyone here being told. The check covers the case that is hard to get wrong and skips the case that is hard to keep right.

It has already happened. Storhaug-ting/Kilden moved its source folders under docs/, and seven cross-repository links in Storhaug-ting/S62 became 404s. A reader found them, not a check – see Storhaug-ting/S62#10.

Acceptance criteria

• A cross-repository link to a file that does not exist fails the check.
• A cross-repository link whose fragment matches no heading in the target fails the check.
• The check is proven negatively: a deliberately wrong target and a deliberately wrong anchor each produce exit code 1, and the output names which link and why.
• A run that resolved no cross-repository link at all is a failure, not a pass, per 📖 [Docs]: A check that checked nothing is a failure, and the docs link check now agrees #134.
• A network or rate-limit failure is reported distinctly from a broken link, so a red run says which of the two happened.

Technical decisions

Scope by ownership, not by scheme. Checking every external URL makes the check slow, flaky, and hostage to other people's outages. Links into organisations we control are a bounded set, and they are where the breakage originates: the target moved because we moved it. The list of in-scope hosts and organisations is a decision this issue must record, not leave to the implementation.

An anchor cannot be checked with a HEAD request. The fragment is never sent to the server, so …/file.md#heading answers 200 whether or not that heading exists. The content has to be fetched and its headings slugged, which is precisely the case that broke in S62.

The oracle must be independent. Anchors have to be derived from GitHub's own slug rules – github-slugger is the reference – not from this repository's ConvertTo-Slug, which mirrors python-markdown for the published site. A cross-repository link resolves against GitHub's rendering, not ours; reusing the site slugger here would check the wrong algorithm and quietly agree with itself.

Answer the third-copy question before it is written. This logic exists twice today: .github/scripts/Test-DocumentationLink.ps1 here, and scripts/Test-MarkdownLink.ps1 in Storhaug-ting/Kilden, adapted from it with GitHub's slug rules instead of the site's. Storhaug-ting/S62#10 is about to make three, in a repository with no .github directory at all. The two slug dialects are a real difference and not duplication to collapse blindly – but whether this ships as a managed file through MSXOrg/Custo rather than being copied and adapted a third time is a question this repository owns, and it is cheaper to answer now than after the third copy exists.

Network calls belong in their own job. A separate job means the name of the red job says the network check failed rather than the docs being wrong. Consider a scheduled run as well: a target repository can move content long after a pull request here has merged, and nothing in the pull-request trigger will ever notice.

Implementation plan

• Decide the in-scope hosts and organisations, and where that list is configured
• Add a failing check first: a link to a non-existent file in a controlled repository, and a link whose anchor matches no heading
• Resolve in-scope cross-repository links against the target content and validate anchors with GitHub's slug rules
• Report a network or rate-limit failure distinctly from a broken link
• Fail a run that resolved no cross-repository link, per 📖 [Docs]: A check that checked nothing is a failure, and the docs link check now agrees #134
• Run the network check as its own job, and decide whether it also runs on a schedule
• State in Markdown.md that cross-repository links are checked, so the standard and the gate say the same thing
• Record whether this ships through MSXOrg/Custo or stays repository-local, so Storhaug-ting/S62#10 and Storhaug-ting/Kilden have an answer to build on

[MariusStorhaug]

Implementation started in #145. Five things the issue body did not have right, or did not have at all, recorded here before they are implemented against.

1. The standard's "canonical published URL" is the Pages URL, not github.com/blob/...

The issue quotes Markdown.md and then reasons entirely about github.com. For MSX repositories the canonical published URL is the Pages site — https://msxorg.github.io/docs/Ways-of-Working/Contribution-Workflow/ — which is the form CONTRIBUTING.md and README.md actually use. So the sentence the issue sets out to cover stays partly uncovered by the work it describes.

It is kept out of this delivery deliberately, because checking it at pull-request time has a false-red built in: a pull request that adds a page and links its published URL fails until that page is published, which is after merge. A follow-up issue carries the gap and that timing problem. Recording it so the next reader does not conclude the standard's sentence is fully gated.

2. Links into this repository must resolve against the checkout, not over the network

Missing from the issue, and it is a false green rather than a gap. https://github.com/MSXOrg/docs/blob/main/tests/Requires-Modules.Tests.ps1 resolved against main over the API passes on a pull request that moves that file, and breaks the moment the pull request merges — the check would confirm the state the change is about to invalidate. Self-repository links therefore resolve against the working tree. It is also faster and needs no API call.

3. Access failure is a third outcome, not a flavour of "network or rate-limit"

The issue lists two outcomes, broken and network/rate-limit. There is a third: a target repository the check cannot read. MSXOrg alone has six private repositories, and GITHUB_TOKEN in Actions is scoped to its own repository, so every other private target answers 404 — indistinguishable from a deleted file unless the repository itself is probed.

This turns out to settle the token question the issue raised. The check's effective visibility is public, and that is the right oracle rather than a limitation to work around: this is a public documentation site, and a page here linking into a private repository is broken for its readers. GITHUB_TOKEN is used only to lift the rate limit from 60 to 1000 requests an hour. So: broken when the repository is readable and the path or anchor is not there; unresolvable when the check could not answer, whether that is a network failure, an exhausted quota, or a target no reader can reach; and both are red, under separate headings.

4. Four links in src/docs are already broken

Probed before writing anything, so the acceptance criteria are measured against real content rather than a fixture:

Link	State
PSModule/Process-PSModule/blob/main/scripts/tests/SourceCode/PSModule/PSModule.Tests.ps1 (pipeline-stages.md:68)	404 — scripts/ no longer exists there
PSModule/Process-PSModule/blob/main/scripts/tests/Module/PSModule/PSModule.Tests.ps1 (pipeline-stages.md:244)	404 — same
PSModule/Process-PSModule/blob/main/DEPENDENCIES.md (process-psmodule/index.md:63)	404 — not in the repository root
MariusStorhaug/.dev/blob/main/.github/Checkout-GitHubRepo.ps1 (Git-Worktrees.md:100)	the repository itself 404s anonymously

The same failure the issue describes from S62, in this repository, undetected. Repairing them is part of the delivery, so the gate can be green for the right reason.

5. Custo cannot be the answer today

The issue asks whether this ships as a managed file through MSXOrg/Custo. MSXOrg/Custo contains LICENSE and README.md and nothing else — there is no managed-file mechanism to ship through, so "distribute rather than copy" is not currently an available choice.

Answer: repository-local, written to be portable rather than distributed. Single file, no repository-specific constants, everything that varies is a parameter — -Path, -Owner, -ApiBaseUri, -SelfRepository. A follow-up issue on Custo carries adoption when distribution exists. Storhaug-ting/S62#10 and Storhaug-ting/Kilden#2 can build on that: copy it, keep the parameters, and the third copy stays a copy of one thing rather than a third dialect.

In-scope hosts and organisations

The list the issue says it must record, now decided:

• Hosts: github.com, raw.githubusercontent.com.
• Owners: MSXOrg, PSModule, Storhaug-ting. Organisations MSX governs, which is where a target moves because we moved it. Personal accounts are out: MariusStorhaug/.dev is not publicly readable, so no check can speak for it.
• Shapes resolved: repository root, ?tab=readme-ov-file#anchor, /blob/{ref}/{path}[#anchor], /tree/{ref}/{path}, and raw.githubusercontent.com/{owner}/{repo}/{ref}/{path}.
• Ignored on purpose: /issues/, /pull/, /discussions/, /releases/, /actions/, /wiki/, /compare/, /commit/. These are API objects, not paths, and they do not move when a repository is restructured.
• Configured as the -Owner parameter's default in .github/scripts/Test-CrossRepositoryLink.ps1, and stated in Markdown.md so the standard names the same set the gate enforces.

On the schedule question

Yes. The check runs in its own workflow — pull_request, push to main, workflow_dispatch, and weekly. Its own workflow rather than a job in Docs.yml for a second reason beyond the name of the red check: publish in Docs.yml has needs: [build, lint, links, test], and a network flake must not be able to block a Pages deploy.