Repository navigation
The docs site is cited by its redirecting alias rather than its canonical domain #186
Description
The docs site is served from https://msx.no/docs/, and https://msxorg.github.io/docs/ returns a 301 redirect to it. Both addresses work today, so nothing is broken, but the repository writes the redirecting alias everywhere and never writes the canonical domain. Readers, downstream repositories, and agents copy whichever form they see first, and the form they see is the alias.
Current state
msxorg.github.io appears 13 times across 7 files. msx.no appears zero times.
README.md— presentsmsxorg.github.io/docsas the published address.CONTRIBUTING.md— 8 links into standards pages.src/docs/Ways-of-Working/Readme-Driven-Context.md— names the site asmsxorg.github.io/docs.src/docs/Coding-Standards/Markdown.md— uses it as the example of "the canonical form for a repository that publishes to GitHub Pages"..github/plugin/msx/plugin.json—homepage..github/scripts/Invoke-PesterSuite.ps1,.github/scripts/Test-CrossRepositoryLink.ps1— doc-comment links.
The repository also carries no CNAME file, so the custom domain is configured only in the Pages settings. That makes the canonical address invisible to anyone reading the repository.
Why it matters
The Markdown standard tells authors that a published-site URL is the canonical form to write, then models that instruction with the alias. Downstream repositories follow the model: PSModule/Template-PSModule links to msxorg.github.io in its AGENTS.md, which every new module repository inherits. An alias that is documented as canonical becomes canonical in practice, and a redirect that everyone depends on is a redirect nobody can retire.
Proposed resolution
- Decide which address is canonical.
msx.no/docs/is the one the redirect points at. - Rewrite the occurrences to the canonical form, including the example in the Markdown standard.
- Add a
CNAMEso the custom domain is visible in the repository rather than only in settings. - State the decision in the Markdown standard, so authors of other repositories have a rule to follow rather than an example to copy.
Technical details
Redirect confirmed with curl -sI -L:
https://msxorg.github.io/docs/ -> HTTP/2 301, location: https://msx.no/docs/
https://msx.no/docs/ -> HTTP/2 200
Both are served by GitHub Pages (server: GitHub.com) from the same deployment, and both return <title>Home - MSX / Docs</title>.
Occurrence count from the default branch:
grep -rn "msxorg.github.io" --include='*.md' src/docs .github AGENTS.md CONTRIBUTING.md README.md | wc -l # 13
grep -rn "msx\.no" --include='*.md' . # 0Found while auditing the links in PSModule/Template-PSModule's AGENTS.md, where 6 of 9 links were dead.
Relevant issues (or links)
Related work
- References Check the published-URL links the Markdown standard also asks authors to write #150 — published-site URLs are not verified by the link checks, which is why alias drift goes unnoticed.
- References ⚙️ [Maintenance]: New module repositories ship the Claude Code and Copilot agent routes PSModule/Template-PSModule#50 — the audit that surfaced this.
Activity