📖 [Docs]: The Markdown standard's cross-repository links are now checked, not just described

[Marius Storhaug (MariusStorhaug)]

Links from these docs into other MSX repositories are now checked in CI. Until now the Markdown standard asked authors to write cross-repository links and nothing verified them, so a target that moved was found by a reader following a dead link rather than by a red check. That has already cost seven links from Storhaug-ting/S62 into Storhaug-ting/Kilden — and, it turns out, six here.

New: Cross-repository links are verified

A link into MSXOrg, PSModule, or Storhaug-ting on github.com or raw.githubusercontent.com is resolved against the target repository. Both halves are checked: the file has to exist, and a #fragment has to match a heading that actually renders there. A URL fragment is never sent to the server, so a HEAD request would answer 200 for an anchor that does not exist — the content is fetched and its headings slugged with GitHub's rules, which are not the rules this site uses. ## Hello — world is #hello--world on GitHub and #hello-world on the published site; write the one GitHub gives you.

Two things follow for authors, and the standard now says both. A public page must not link into a repository a reader cannot open — the check reads targets as an anonymous reader does, so a private target is reported. And a run that resolved no cross-repository link at all fails, because every link resolves is trivially true over an empty set.

A link the check could not answer — a network failure, an exhausted API rate limit, or a target nobody outside can reach — is reported under its own heading, separate from a broken link, so a red run says which of the two happened.

It runs as its own check, Cross-repository links, on every pull request and push to main, and again weekly: a target repository moves content long after a pull request here has merged, and nothing in the pull-request trigger would ever notice.

Fixed: Six dead links into PSModule repositories

Every one of these was a live 404 in published documentation:

Page	What happened
Pipeline stages ×2	Process-PSModule moved its framework tests from scripts/tests to .github/actions/Test-PSModule/src/tests
Pipeline stages ×2	Test-PSModule's README no longer has the SourceCode tests and Module tests sections two anchors pointed at
Pipeline stages	Publish-Docs.yml is now Publish-Site.yml
Process-PSModule overview	DEPENDENCIES.md no longer exists, and has no successor anywhere in the organization

The Checkout-GitHubRepo link in Git Worktrees is kept and marked private: the file is there, the repository is not public, so a reader who gets a 404 now knows why.

---

Technical details

Proven red before green. The suite was written and committed before the script existed. Beyond that, two mutations were run against the finished check: disabling the anchor comparison turned exactly the two anchor cases red, and treating a 404 as success turned exactly the missing-file and unreadable-repository cases red — so the cases measure what their names claim. Then the live proof: two links in pipeline-stages.md were pointed deliberately wrong, one at a missing file and one at a missing anchor, and pushed. The run went red naming both links with the right classification on each; the commit was reverted and the run went green.

Files. .github/scripts/Test-CrossRepositoryLink.ps1 (new), tests/Test-CrossRepositoryLink.Tests.ps1 (new, 31 cases), .github/workflows/Cross-Repository-Links.yml (new), .github/workflows/Docs.yml, .github/linters/.codespellrc, src/docs/Coding-Standards/Markdown.md, CONTRIBUTING.md, and the four documentation pages carrying the repaired links.

Decisions recorded on #142, together with five corrections to the issue body found while implementing it:

• In-scope hosts github.com and raw.githubusercontent.com; owners MSXOrg, PSModule, Storhaug-ting — the organizations MSX controls, which is where a target moves because we moved it. Configured as the -Owner default. Shapes resolved: repository root, ?tab=readme-ov-file#anchor, /blob/{ref}/{path}, /tree/{ref}/{path}, raw…. /issues/, /pull/, /discussions/, /releases/, /actions/, /wiki/, /compare/, /commit/ are ignored: API objects, not paths, and they do not move when a repository is restructured.
• A 404 alone cannot tell a deleted file from a repository nobody can open, so the repository is probed before a link is called broken. That gives three outcomes rather than the issue's two, and settles the token question: GITHUB_TOKEN is used only for rate-limit headroom (60 → 1000 requests/hour) and unlocks no private repository elsewhere, so the effective visibility is public — the right bar for a public documentation site.
• Links into this repository resolve against the checkout, not against main over the API. Resolved remotely, a pull request that moves a file would pass here and break as it merged. Not in the issue body; added to it.
• The quota is a run-level fact. The first 403 with no remaining quota stops the rest — found by running locally without a token, where the check spent two dozen further requests being told the same thing. The message now also says when no token was set, since that is the one thing that would have changed the outcome.
• Anchors come from ConvertTo-GitHubSlug and Get-RenderedHeadingText, taken from Storhaug-ting/Kilden, not from this repository's ConvertTo-Slug, which mirrors python-markdown for the published site and would check the wrong algorithm. A one-character error in Kilden's own example was found in the process — 📖 [Docs]: Slug example now shows the anchor the function actually produces Storhaug-ting/Kilden#16.
• Repository-local rather than distributed through MSXOrg/Custo, because Custo contains LICENSE and README.md and no managed-file mechanism, so there is nothing to ship through. The script is written to be portable instead: single file, no repository-specific constants, everything that varies is a parameter, and the repository it runs in comes from GITHUB_REPOSITORY or the git remote. Adoption is carried by Distribute the Markdown link check instead of copying it a fourth time Custo#6, and the answer is reported to Storhaug-ting/S62#10.
• Published-URL (Pages) links are still unchecked and that is deliberate — a pull request adding a page and linking its published URL would fail until the page is published. Check the published-URL links the Markdown standard also asks authors to write #150 carries the gap and the timing problem.

Testing. The suite runs fully offline: an in-process System.Net.HttpListener stub answers the two GitHub endpoints the check calls, so the missing-file, missing-anchor, rate-limit, request-failure, unreadable-repository, deduplication, and short-circuit cases are deterministic and locally runnable. The seam is -ApiBaseUri, which follows GITHUB_API_URL and is a real feature rather than a test hook — it is what makes the script work against GitHub Enterprise Server. The fourteen slug expectations are a recorded fixture from github-slugger 2.0.0 rather than a second derivation of the rule under test; the PowerShell implementation matches it on all fourteen.

Verified. Invoke-PesterSuite.ps1: 85 passed, 0 failed across 5 suites. PSScriptAnalyzer with .github/linters/.powershell-psscriptanalyzer.psd1: clean on both new files. Test-DocumentationLink.ps1: 114 files, all resolve. Test-CrossRepositoryLink.ps1: 34 links in 121 files, all resolve. Update-DocumentationIndex.ps1 -Check: clean. markdownlint-cli2 and codespell with the repository's configs: clean — and the codespell change was negative-tested against a probe containing mispelled and sentance, which still produces two errors, so the new ignore-regex did not blanket-disable spell checking.

Implementation plan progress: all eight steps of #142 complete. Nothing deferred except the published-URL form, which was never in that issue's scope and is now #150.

Standards and framework alignment pass

Changed surface	Standards checked	Framework docs checked	Result
.github/scripts/** (PowerShell)	PowerShell/Scripts, PowerShell/Functions, Naming, Error Handling, Documentation	None (no framework-specific docs)	Aligned
tests/** (PowerShell)	Testing, PowerShell/Testing, PowerShell/Functions	None (no framework-specific docs)	Aligned
.github/workflows/**	GitHub Actions	None (no framework-specific docs)	Aligned
.github/linters/**	Markdown, Natural Language	None (no framework-specific docs)	Aligned
src/docs/**, CONTRIBUTING.md	Markdown, Documentation, Natural Language	Documentation Model	Aligned

Issue convergence sweep. Scoped to open issues about link checking, documentation gates, and the repositories this touches: #142 (closed by this), #150 (opened by this, not satisfied by it), MSXOrg/Custo#6 (opened by this), Storhaug-ting/S62#10 and Storhaug-ting/Kilden#12 (both answered, neither delivered — the check they need lives in their own repositories). #134's rule is honoured here but that pull request is already merged.

Relevant issues (or links)

• Fixes Check the cross-repository links the Markdown standard tells authors to write #142
• Check the published-URL links the Markdown standard also asks authors to write #150
• 📖 [Docs]: A check that checked nothing is a failure, and the docs link check now agrees #134
• Distribute the Markdown link check instead of copying it a fourth time Custo#6
• Storhaug-ting/S62#10
• 📖 [Docs]: Slug example now shows the anchor the function actually produces Storhaug-ting/Kilden#16

[Copilot]

Pull request overview

This PR adds CI validation for cross-repository links (into MSX-controlled GitHub orgs) so that moved files/anchors in other repositories are detected automatically, and it repairs several existing dead cross-repo links in the documentation.

Changes:

• Introduces a new PowerShell validator (Test-CrossRepositoryLink.ps1) plus an offline Pester suite with an in-process stub GitHub API.
• Adds a dedicated GitHub Actions workflow (Cross-Repository-Links.yml) to run the cross-repository link check on PRs/pushes and weekly.
• Updates documentation/standards and repairs broken links into PSModule repositories.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/Test-CrossRepositoryLink.Tests.ps1	Adds offline Pester coverage for cross-repository link parsing, resolution, anchoring, caching, and failure classification.
./.github/scripts/Test-CrossRepositoryLink.ps1	Implements the cross-repository link checker (GitHub API resolution + GitHub-style anchor validation).
.github/workflows/Cross-Repository-Links.yml	New workflow to run the cross-repo link check (PR/push + weekly schedule).
.github/workflows/Docs.yml	Clarifies that the existing Links job is intentionally network-free and that cross-repo checking lives elsewhere.
CONTRIBUTING.md	Documents running the new cross-repository link check locally before opening a PR.
src/docs/Coding-Standards/Markdown.md	Documents that links are checked and describes the new cross-repo check’s behavior/scope.
src/docs/Ways-of-Working/Git-Worktrees.md	Adds context that a referenced helper script link points to a private repository.
src/docs/Capabilities/process-psmodule/pipeline-stages.md	Repairs multiple PSModule cross-repo links to moved/renamed targets.
src/docs/Capabilities/process-psmodule/index.md	Replaces an obsolete dependency reference with links to current workflow/action structure.
.github/linters/.codespellrc	Avoids false positives from \p{...} Unicode-category escapes used in regexes.

Suppressed comments (2)

src/docs/Coding-Standards/Markdown.md:67

• Test-CrossRepositoryLink.ps1 is described here as resolving links "as published URLs", but the very next bullet scopes it to github.com and raw.githubusercontent.com. Rewording this to explicitly say “GitHub URLs” avoids confusion with published-site (Pages) URLs.

**Into another repository** — `Test-CrossRepositoryLink.ps1` resolves the links this standard asks you to write as published URLs. It runs as its own job, so a red check says the network check failed rather than the documentation being wrong, and again weekly, because a target repository moves content long after a pull request here has merged.

src/docs/Capabilities/process-psmodule/pipeline-stages.md:244

• Grammatically, “tests” is plural, so the verb should be “verify” (or rephrase to a singular subject like “test suite”).

The [PSModule - Module tests](https://github.com/PSModule/Process-PSModule/blob/main/.github/actions/Test-PSModule/src/tests/Module/PSModule/PSModule.Tests.ps1) verifies the following coding practices that the framework enforces:

[Marius Storhaug (MariusStorhaug)]

Right, and that sentence was doing exactly what this pull request exists to stop — a standard claiming a gate it does not have.

Fixed in d00db90. The bullet now says relative links, and cross-repository links on \github.com, are checked in CI, the section says the check resolves \github.com\ links rather than 'the links this standard asks you to write as published URLs', and there is a paragraph naming what is not covered: a \msxorg.github.io\ URL, which is the canonical form for a repository publishing to Pages. That gap is #150, which also records why it was not simply added here — a pull request adding a page and linking its published URL would fail until the page is published.

[Copilot]

Pull request overview

Copilot reviewed 10 out of 10 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/docs/Capabilities/process-psmodule/pipeline-stages.md:66

• Grammar: this sentence is missing “to” (“…is used by … evaluate…”). As written it’s ungrammatical and slightly harder to read in the rendered docs.

  - [PSModule framework settings for style and standards for source code](https://github.com/PSModule/Process-PSModule/tree/main/.github/actions/Test-PSModule/src/tests/SourceCode)
- This produces a JSON-based report that is used by [Get-PesterTestResults](#get-test-results) evaluate the results of the tests.