feat: Broken link detection at build time

[swernerx]

Summary

Add automatic broken link detection during the build process, warning about internal links that point to non-existent pages or anchors.

Motivation

Broken links are one of the most common documentation quality issues, especially as docs grow and pages get renamed or reorganized. Mintlify checks for broken links automatically. Build-time detection catches issues before they reach users.

Proposed Features

• Detect broken internal page links (e.g., /guide/nonexistent)
• Detect broken anchor links (e.g., /guide/intro#nonexistent-heading)
• Configurable behavior: warn (default) or error (fail build)
• Exclude patterns for known external/dynamic links
• Report with file path and line number

Configuration

ardo({
  linkCheck: {
    enabled: true,           // default: true
    level: 'warn',           // 'warn' | 'error'
    exclude: ['/api/*'],     // patterns to skip
    checkAnchors: true,      // check #anchor links
  }
})

Implementation Ideas

• Collect all internal links during MDX processing (remark plugin)
• Compare against known routes from route generation
• For anchor checking, compare against extracted headings
• Run as a post-build validation step
• Could also check external links optionally (with timeout/caching)

[swernerx]

Triage note:

• T-shirt size: M
• Product relevance: Very often required
• Assessment: This is one of the highest-value quality features for a docs framework and fits Ardo's promise of catching mistakes early. The harder parts are anchor validation, clear diagnostics, and choosing when warnings should escalate to build failures.