Link Validation

Dual-layer link validation system using TypeScript (compile-time) and runtime Set checks to prevent broken documentation links.

Why It Matters

Catch broken links during development (TypeScript errors)
Visual feedback in browser (red underline)
Maintain documentation quality as your API evolves
Build confidence in your docs

Two Validation Layers

Compile-Time (TypeScript)

TypeScript validates link targets before build:

<RefLink target="mint-tsdocs.MarkdownDocumenter" /> // ✅ Valid
<RefLink target="mint-tsdocs.NonExistent" />        // ❌ Type error in IDE

<PageLink target="quickstart" />      // ✅ Valid
<PageLink target="fake-page" />       // ❌ Type error in IDE

Benefits: Instant IDE feedback, prevents bad commits, autocomplete suggestions

Runtime (Set Membership)

Browser checks if targets exist in auto-generated Sets:

// RefLink check
const isValid = VALID_REFS.has('mint-tsdocs.MarkdownDocumenter');

// PageLink check
const isValid = VALID_PAGES.has('quickstart');

Benefits: Works without TypeScript, visual broken-link styling, graceful degradation

Auto-Generated Files

Running mint-tsdocs generate creates three validation file pairs:

ValidRefs (API References)

ValidRefs.jsx

export const VALID_REFS = new Set([
  'mint-tsdocs.MarkdownDocumenter',
  'mint-tsdocs.MarkdownDocumenter.generateFiles',
  'mint-tsdocs.CacheManager',
  // ... all API items
]);

ValidRefs.d.ts

export type RefId =
  | 'mint-tsdocs.MarkdownDocumenter'
  | 'mint-tsdocs.CacheManager'
  // ... all API items

export const VALID_REFS: Set<RefId>;

Used by: RefLink Location: docs/snippets/tsdocs/ValidRefs.*

ValidPages (Documentation)

ValidPages.jsx

export const VALID_PAGES = new Set([
  'introduction',
  'quickstart',
  'guides/setup-guide',
  'concepts/coverage',
  // ... all pages from docs.json
]);

ValidPages.d.ts

export type PageId =
  | 'introduction'
  | 'quickstart'
  // ... all pages

export const VALID_PAGES: Set<PageId>;

Used by: PageLink Location: docs/snippets/tsdocs/ValidPages.*

Validation Flow

Write link in MDX

<RefLink target="mint-tsdocs.MarkdownDocumenter" />

TypeScript validates (edit time)

IDE checks target against type definitions, shows errors immediately

Component renders (runtime)

Browser checks Set membership: VALID_REFS.has(target)

Visual feedback

Valid: normal link
Invalid: red underline + “broken-link” CSS class

Broken Link Styling

Default CSS (customizable via docs/style.css):

.prose .tsdocs-reflink.broken-link,
.prose .tsdocs-pagelink.broken-link {
  border-bottom: 2px dotted #ef4444 !important;
  color: #ef4444 !important;
  text-decoration: wavy underline !important;
}

Visual indicators:

Red color: #ef4444 (light mode), #f87171 (dark mode)
Red dotted underline: 2px
Red wavy text decoration
Tooltip: “Broken API reference: ” or “Broken page link: ”

See Custom Styles for customization.

When Links Break

Component	Common Causes
RefLink	API item renamed, deleted, not exported, typo in RefId
PageLink	Page removed from docs.json, renamed, moved, typo in path

Fixing Broken Links

RefLink
PageLink

Check TypeScript error
Find correct RefId in API reference
Update target prop
Run mint-tsdocs generate if source changed

Check TypeScript error
Find correct path in docs.json
Update target prop
Run mint-tsdocs generate if navigation changed

Performance

The validation system is designed for minimal impact: Compile-time: Zero runtime cost, instant IDE feedback Runtime: O(1) Set lookups, small payload (few KB), no network requests

Troubleshooting

Validation files not found

Run mint-tsdocs generate to create files in docs/snippets/tsdocs/

TypeScript not detecting errors

Check .d.ts files exist
Restart TypeScript server (VS Code: Cmd+Shift+P → “Restart TS Server”)
Verify tsconfig.json includes snippets folder

All links showing broken

Check browser console for import errors
Clear cache and hard refresh
Run mint-tsdocs generate to sync validation files

Best Practices

Run mint-tsdocs generate after API or navigation changes

Enable TypeScript in MDX for compile-time validation

Test locally with mint dev before publishing

Fix broken links before committing

RefLink

Uses ValidRefs

PageLink

Uses ValidPages

TypeInfo

Auto-generated types

Get Started

Usage

Components & Snippets

AI Tools

Why It Matters

Two Validation Layers

Compile-Time (TypeScript)

Runtime (Set Membership)

Auto-Generated Files

ValidRefs (API References)

ValidPages (Documentation)

Validation Flow

Broken Link Styling

When Links Break

Fixing Broken Links

Performance

Troubleshooting

Best Practices

RefLink

PageLink

TypeInfo

​Why It Matters

​Two Validation Layers

​Compile-Time (TypeScript)

​Runtime (Set Membership)

​Auto-Generated Files

​ValidRefs (API References)

​ValidPages (Documentation)

​Validation Flow

​Broken Link Styling

​When Links Break

​Fixing Broken Links

​Performance

​Troubleshooting

​Best Practices

​Related

RefLink

PageLink

TypeInfo

Why It Matters

Two Validation Layers

Compile-Time (TypeScript)

Runtime (Set Membership)

Auto-Generated Files

ValidRefs (API References)

ValidPages (Documentation)

Validation Flow

Broken Link Styling

When Links Break

Fixing Broken Links

Performance

Troubleshooting

Best Practices

Related