Automated checks for internal links and assets

[yinxulai]

Summary

Clarify should provide automated checks for internal documentation links, heading anchors, and static assets so migrations like Apollo can catch broken references before release.

Problem

During Apollo's Docsify-to-Clarify migration review, we identified a large number of existing internal references that need validation:

• /#/... legacy routes
• ?id= heading anchors
• .md cross-page links
• local images and other static assets

These references can break during content or routing migrations even when the build itself succeeds.

Why this matters

A successful build does not guarantee that the generated site is navigable. We need a way to detect:

• missing pages
• invalid heading anchors
• broken relative links
• missing static assets
• regressions introduced by navigation or content moves

Scope

This issue is about a migration-friendly validation layer for Clarify. The goal is to make link and asset integrity easy to verify in CI or as a local preflight check.

Possible checks:

• crawl generated pages and validate internal links
• verify heading anchors exist for all referenced fragments
• check that local assets are emitted into the output directory
• report broken links with file-level context
• optionally fail the build or provide a dedicated command

Acceptance criteria

• Users can run an automated check that catches broken internal links before publishing.
• The check reports missing pages, anchors, and assets with actionable diagnostics.
• The check works well for large documentation sites with many cross-page references.

Related

• Apollo migration review: draft(docs): switch documentation to Clarify with minimal configuration apolloconfig/apollo#5648
• Migration compatibility issue: Legacy link compatibility for Apollo migrations #35

[yinxulai]

Related Apollo PR: apolloconfig/apollo#5648

This issue tracks automated checks for internal links, anchors, and static assets raised during the Apollo documentation migration review.