Skip to main content
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

1

Write link in MDX

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

TypeScript validates (edit time)

IDE checks target against type definitions, shows errors immediately
3

Component renders (runtime)

Browser checks Set membership: VALID_REFS.has(target)
4

Visual feedback

  • Valid: normal link
  • Invalid: red underline + “broken-link” CSS class
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.
ComponentCommon Causes
RefLinkAPI item renamed, deleted, not exported, typo in RefId
PageLinkPage removed from docs.json, renamed, moved, typo in path

​
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

Run mint-tsdocs generate to create files in docs/snippets/tsdocs/
  1. Check .d.ts files exist
  2. Restart TypeScript server (VS Code: Cmd+Shift+P → “Restart TS Server”)
  3. Verify tsconfig.json includes snippets folder

​
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