Add support for checking for broken links

[delucis]

It would be good to offer some basic tooling to ensure the integrity of internal links within sites built with Starlight. Many broken links can make a site frustrating to use.

Some prior art:

• Astro’s Docs has a complex [link checking script(https://github.com/withastro/docs/blob/main/scripts/lint-linkcheck.ts), which runs against build output and makes sure links are not only not broken, but are in the right language (e.g. no /en/ links on a /fr/ page), ensures links end in a trailing slash (the canonical for that site), don’t use an inaccessible label like “read more”, use a relative path (for links within the site — guarantees functionality in staging contexts), etc.

• @HiDeoo just published a dedicated Starlight integration for this: starlight-links-validator and left some comments: Fix various docs broken links #246 (comment) (thanks @HiDeoo!)

• VitePress has an ignoreDeadLinks config option, so presumably checks for them although there’s no documentation.

• Docusaurus has onBrokenLinks and onBrokenMarkdownLinks config options to control what level of error/warning to show on bubild.

There’s some questions about what built-in tooling for Starlight could look like, what config would be needed etc., but would definitely be cool to explore!

[lschierer]

is that starlight-links-validator specific to the actual starlight documentation site?

[stereobooster]

I have experimental project which may help with the task. Basic idea: file watcher + markdown parser + db = "markdown-graph-content-layer-database". Usage looks something like this:

const bdb = new BrainDB({
  root: path.resolve(process.cwd(), "src/content/docs"),
  url: (filePath, _frontmatter) => `${generateSlug(filePath)}/`,
});
bdb.start();

bdb.on("*", (_action, opts) => {
  if (opts) {
    opts.document
      .unresolvedLinks()
      .forEach((link) =>
        console.log(
          `Unresolved link: ${link
            .from()
            .path()}:${link.line()}:${link.column()}`
        )
      );
  }
});