feat(website): add starlight-links-validator to catch broken internal links#119
Merged
feat(website): add starlight-links-validator to catch broken internal links#119
Conversation
GitHub Pages serves every page at a trailing-slash URL (e.g. /AstroChart/quickstart/). From such a URL, `./guides/foo` resolves to /AstroChart/quickstart/guides/foo instead of /AstroChart/guides/foo. Fix all cross-directory relative links on top-level pages to use `../` instead of `./` when navigating into subdirectories: - quickstart.mdx: 7 links (Next Steps + Troubleshooting) - introduction.mdx: 2 links (guides/radix-chart, api/chart) - installation.md: 5 links (compatibility table + Next Steps) - changelog.md: 1 dead link replaced (guides/getting-started → ../introduction) Also: - astro.config.mjs: remove bare favicon '/favicon.svg' (Starlight auto-discovers public/favicon.svg); add trailingSlash: 'always' so dev server matches GitHub Pages behavior and catches link bugs early - AGENTS.md: add 'Website / Astro link strategy' section with a per-depth reference table and future domain migration note 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
trailingSlash: 'always' in astro.config.mjs makes the dev server enforce
slash-terminated URLs (mirroring GitHub Pages). withBase was producing
slash-less paths (e.g. /AstroChart/installation) which the strict dev
server no longer matched, breaking the Get Started and other hero links.
Fix: append a trailing slash in withBase if not already present.
withBase('/installation') → '/AstroChart/installation/'
All callers in index.astro are fixed automatically. No other files change.
Edge cases verified:
base: '/AstroChart' → /AstroChart/installation/ ✅
base: '/' → /installation/ ✅ (future astrochart.dev)
🤖 Generated with [eca](https://eca.dev)
Co-Authored-By: eca <git@eca.dev>
Root-level pages use trailing-slash URLs (e.g. /AstroChart/introduction/). ./sibling from such a URL resolves to /AstroChart/introduction/sibling — wrong. All sibling links on root pages must use ../ to reach /AstroChart/sibling. introduction.mdx: ./installation, ./quickstart (×2), ./contributing → ../ installation.md: ./quickstart → ../quickstart These were missed in the first pass which only fixed cross-directory links. Full project audit confirmed no other broken relative links remain. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
The link strategy table incorrectly said root pages use './' for sibling root pages. That was the exact mistake that caused two broken-link passes. Corrected: root pages use '../' for ALL targets (siblings and subdirs) because the trailing-slash URL makes the browser treat the page as a directory. Added an explanatory callout making the 'why' explicit so the rule is impossible to misread. Added a mandatory link audit rule: any task touching content files or trailingSlash/base config must end with a full grep of src/content/docs/ to verify no root-level page retains any './' link. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
… in dev Astro markdown pipeline emits relative hrefs verbatim (no trailing slash). trailingSlash: always makes the dev server 404 every one of the ~50 relative links in the content tree. GitHub Pages issues a silent 301 for slash-less URLs in production so links work fine without the strict setting. AGENTS.md: added explicit do-not-add warning explaining the tension with the markdown pipeline. Removed the incorrect claim that the setting catches bugs. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
… links Install starlight-links-validator@0.21.0 and register it as a Starlight plugin. Validation runs only on `npm run build` (skipped in dev mode to keep `astro dev` fast). Configuration: `errorOnRelativeLinks: false` — all internal links use relative paths so the site can be migrated to a different base (e.g. astrochart.dev) by changing only `astro.config.mjs`. Hash fragments (e.g. `#valid-planet-keys`) are still validated. Also fixes two pre-existing broken links in guides/frameworks/ where `../multiple-charts` was one level short and should be `../../multiple-charts`. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
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
1 participant
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.
Summary
starlight-links-validator@0.21.0as a Starlight plugin — validates internal links at build time and fails the build if any are brokenerrorOnRelativeLinks: falseso all content links stay in relative form (migration toastrochart.devonly requires changingbaseinastro.config.mjs, no content files touched)astro devto keep local iteration fast; runs only onnpm run build#valid-planet-keys) remains activeguides/frameworks/angular.mdandguides/frameworks/vue.mdwhere../multiple-chartswas one level short (correct form is../../multiple-charts)Test plan
npm run buildfromwebsite/completes withAll internal links are valid.npm run devfromwebsite/starts without running the validatornpm run buildandnpm testfrom repo root still pass (library unaffected)🤖 Generated with eca