Broken Link Detection

Holocron checks every internal link in your MDX files during build and dev server startup. When a link points to a page that doesn't exist in the navigation tree, a warning is printed to the terminal:

1▲ holocron broken link /quickstart:12 → /missing-page (no matching page found)

The warning includes the source file, the line number, and the broken href so you can fix it quickly.

What gets checked

Holocron scans two types of links:

Markdown links

123[Getting Started](/getting-started)
[Next section](./next)
[Parent page](../overview)

JSX component hrefs

123<Card href="/quickstart">Get Started</Card>
<Tile href="/guides/deploy">Deploy</Tile>
<a href="/api/overview">API Reference</a>

Components checked: a, Card, Tile, Tooltip, Badge.

What is not checked

These links are skipped and never produce warnings:

External URLs: https://example.com, http://...
Anchor-only links: #section-id
Special protocols: mailto:, tel:, javascript:
Static files: paths with file extensions like /openapi.json, /guide.pdf, /logo.png
Dynamic JSX expressions: <Card href={dynamicUrl}> (only static string attributes are checked)

How links are resolved

Absolute links like /getting-started are matched directly against page hrefs in your navigation tree.

Relative links like ./next or ../overview are resolved from the linking page's directory. For example, a link ./deploy inside guides/setup.mdx resolves to /guides/deploy.

Hash fragments and query strings are stripped before matching. /setup#installation checks whether /setup exists as a page.

Valid link targets

A link is considered valid if it matches any of:

A page in the navigation tree
A redirect source defined in redirects
A path declared in knownPaths

Known paths

When your docs app is mounted alongside other routes (API endpoints, dashboards, external apps), links to those routes would trigger false warnings. Use knownPaths to declare paths that exist outside of Holocron:

123{
  "knownPaths": ["/api/*", "/dashboard", "/blog/*"]
}

Exact paths

"/dashboard" matches only /dashboard.

Wildcard prefixes

"/api/*" matches /api/users, /api/v2/auth, and any other path starting with /api/.

Example

A Spiceflow custom entry that serves both docs and an API:

123456{
  "navigation": [
    { "group": "Docs", "pages": ["index", "quickstart"] }
  ],
  "knownPaths": ["/api/*", "/health"]
}

Now a link like [API Reference](/api/overview) in your MDX won't trigger a warning, even though /api/overview isn't an MDX page.

When it runs

Link validation runs as part of the sync phase, which processes all MDX files and builds the navigation tree. This happens:

On npx vite build (production build)
On dev server startup (npx vite)
On HMR when an MDX file or the config file changes

The sync phase first parses every page and collects all internal links, then validates them against the fully built navigation tree. This means links are checked after all pages (including OpenAPI-generated ones) are registered.

Caching

Link data is cached alongside other page metadata in dist/holocron-mdx.json. When an MDX file hasn't changed between builds, its links are restored from cache without re-parsing. Validation still runs on every sync, just the link extraction step is skipped for unchanged files.