starlight-links-validator

starlight-links-validator is a build-time plugin for Starlight, the documentation site framework built on Astro. It walks every Markdown and MDX page in a Starlight site, extracts internal links — including the built-in <LinkCard> and <LinkButton> components as well as any custom components you register — and confirms each one resolves to a real page, asset, or in-page heading anchor before the build finishes.

Rather than bolting on an external link-checker that crawls a deployed site after the fact, the plugin runs inside the Astro build pipeline itself via the official plugin and integration hooks, so it has direct access to resolved routes, redirects, locale fallbacks, and the content layer cache. It reports invalid links, invalid hashes, relative links, local links, and same-site links with precise file and line positions, and can fail the build (failOnError) or just warn, with dedicated reporters for the CLI, GitHub Actions job summaries, and JSON output for programmatic consumption.

What You Get

• Automatic validation of internal links and in-page/cross-page hash anchors across all Markdown and MDX content
• Awareness of Astro-resolved routes, redirects (internal and external), and Starlight’s locale-fallback pages
• Configurable error policies for relative links, local links, fallback pages, inconsistent-locale links, and same-site absolute URLs
• Glob-based or function-based link exclusion for cases the validator shouldn’t check
• CLI, GitHub Actions job-summary, and JSON reporters out of the box

Common Use Cases

• Gating pull requests on a documentation site so broken internal links fail CI before merge
• Auditing a large docs restructuring or rename pass for every link that needs updating
• Enforcing consistent link behavior across multi-locale Starlight sites
• Surfacing broken-link results directly in a GitHub Actions job summary for open-source contributors

Under The Hood

Architecture The plugin registers itself as a Starlight plugin that, during the config:setup hook, stores validation configuration and adds both a route middleware and a nested Astro integration; the integration hooks into astro:config:setup to attach a markdown-processor plugin (libs/processor.ts dispatches between the newer satteri processor and the unified/rehype pipeline via libs/satteri.ts and libs/rehype.ts), into astro:routes:resolved to capture resolved routes, and into astro:build:done to run validateLinks (libs/validation.ts) against the collected link data, page set, and redirect map. Concerns are cleanly separated across single-purpose modules — libs/path.ts for pathname normalization, libs/i18n.ts for locale/fallback logic, libs/position.ts for source-position resolution, libs/store.ts for cross-hook state — so the core validateLink function stays a straightforward decision tree over a ValidationContext rather than a monolith.

Tech Stack Written in strict TypeScript on top of Astro 7 and Starlight, using Astro’s own zod re-export for the options schema (libs/config.ts), picomatch for glob-based exclusion, hast-util-from-html/mdast-util-to-hast/unist-util-visit/mdast-util-mdx-jsx for AST traversal across both supported markdown processors, github-slugger for heading-to-hash slug parity with Starlight, and yaml for frontmatter parsing. The monorepo is managed with pnpm workspaces and Changesets for release automation, with a separate docs/ package building the project’s own Starlight-based documentation site.

Code Quality The test suite (~1,235 lines across ~19 files) runs real astro build invocations against dedicated fixture projects and asserts on the actual rendered CLI diagnostic output via regex, exercised in CI across both the satteri and unified markdown processors and both Ubuntu and Windows runners — a notably thorough integration-style testing approach rather than isolated unit mocks. The codebase uses strict TypeScript throughout, an ESLint config extending a shared preset, and JSDoc comments documenting every user-facing option’s defaults and behavior in libs/config.ts.

What Makes It Unique Unlike a generic external link-checker that crawls a deployed site’s HTML after the fact, this plugin runs inside Astro’s own build lifecycle, giving it access to information a crawler cannot easily reconstruct: resolved route redirects (internal vs. external), Starlight’s locale-fallback page behavior, and the content-layer cache, which the plugin proactively invalidates so link data stays accurate across incremental builds. That build-time integration is the core differentiator; the link-validation domain itself is well-trodden.