> ## Documentation Index
> Fetch the complete documentation index at: https://mint-tsdocs.saulo.engineer/llms.txt
> Use this file to discover all available pages before exploring further.

# RefLink

> Type-safe links to API reference pages with validation

export const Preview = ({children, title = "Preview", className}) => {
  const outerClasses = ["code-block mt-5 mb-8 not-prose rounded-2xl relative group", "text-gray-950 bg-gray-50 dark:bg-white/5 dark:text-gray-50", "border border-gray-950/10 dark:border-white/10", "p-0.5", className].filter(Boolean).join(" ");
  return <div className={outerClasses} data-component="tsdocs-preview">
      {}
      <div className="flex text-gray-400 text-xs rounded-t-[14px] leading-6 font-medium pl-4 pr-2.5 py-1">
        <div className="flex-none flex items-center gap-1.5 text-gray-700 dark:text-gray-300">
          {title}
        </div>
      </div>

      {}
      <div className="prose prose-sm dark:prose-invert w-0 min-w-full max-w-full py-3.5 px-4 rounded-b-2xl bg-white dark:bg-codeblock overflow-x-auto scrollbar-thin scrollbar-thumb-rounded scrollbar-thumb-black/15 hover:scrollbar-thumb-black/20 dark:scrollbar-thumb-white/20 dark:hover:scrollbar-thumb-white/25">
        {children}
      </div>
    </div>;
};

export const RefLink = ({target, children}) => {
  if (!target || typeof target !== 'string') {
    console.error('RefLink: Invalid target prop. Expected non-empty string.');
    return <span className="tsdocs-reflink broken-link" title="Invalid RefLink target" data-component="tsdocs-reflink">Invalid Link</span>;
  }
  const linkText = children || target;
  const path = typeof window !== 'undefined' && window.getRefPath ? window.getRefPath(target) : `./${target.split('.').filter(s => s.length > 0).join('/')}`;
  const isValid = typeof window !== 'undefined' && window.VALID_REFS && window.VALID_REFS.has(target);
  const className = !isValid ? 'tsdocs-reflink broken-link' : 'tsdocs-reflink';
  const title = !isValid ? `Broken API reference: ${target}` : undefined;
  return <a href={path} className={className} title={title} data-component="tsdocs-reflink">
      {linkText}
    </a>;
};

Type-safe links to API reference pages with compile-time TypeScript validation and runtime checking.

## Basic Usage

```jsx theme={null}
import { RefLink } from "/snippets/tsdocs/RefLink.jsx"

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

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

<Preview title="Default link text">
  <RefLink target="mint-tsdocs.MarkdownDocumenter" />
</Preview>

With custom text:

```jsx theme={null}
<RefLink target="mint-tsdocs.CacheManager">caching system</RefLink>
```

<Preview title="Custom link text">
  Learn more about the <RefLink target="mint-tsdocs.CacheManager">caching system</RefLink>.
</Preview>

## Properties

<ParamField path="target" type="string" required>
  API reference ID: `PackageName.ClassName.MemberName`

  Examples: `mint-tsdocs.MarkdownDocumenter`, `mint-tsdocs.loadConfig`, `mint-tsdocs.CacheManager.typeAnalysis`
</ParamField>

<ParamField path="children" type="ReactNode">
  Link text. Defaults to the API item name if omitted.
</ParamField>

## Type Safety

RefLink validates links in two ways:

**Compile-time** - TypeScript checks against `ValidRefs.d.ts`:

```typescript theme={null}
<RefLink target="mint-tsdocs.MarkdownDocumenter" /> // ✅ Valid
<RefLink target="mint-tsdocs.NonExistent" />        // ❌ Type error
```

**Runtime** - Browser checks against `ValidRefs` Set and applies styling:

<Preview title="Valid vs broken links">
  <div className="space-y-2">
    <div>✅ Valid: <RefLink target="mint-tsdocs.MarkdownDocumenter">MarkdownDocumenter</RefLink></div>
    <div>❌ Broken: <RefLink target="mint-tsdocs.NonExistentClass">NonExistentClass</RefLink></div>
  </div>
</Preview>

Broken links get:

* Red color (#ef4444)
* Red dotted underline (2px)
* Red wavy text decoration
* Tooltip showing the error

Learn more: [Link Validation](/components/link-validation)

## Examples

<Preview title="Linking to different API items">
  <div className="space-y-2">
    <div>Interface: <RefLink target="mint-tsdocs.MintlifyTsDocsConfig" /></div>
    <div>Class: <RefLink target="mint-tsdocs.MarkdownDocumenter" /></div>
    <div>Method: <RefLink target="mint-tsdocs.CacheManager.getStats" /></div>
    <div>Function: <RefLink target="mint-tsdocs.loadConfig" /></div>
  </div>
</Preview>

## RefId Format

API reference IDs follow: `PackageName.ClassName.MemberName`

Examples:

* Class: `mint-tsdocs.MarkdownDocumenter`
* Method: `mint-tsdocs.MarkdownDocumenter.generateFiles`
* Interface property: `mint-tsdocs.MintlifyTsDocsConfig.entryPoint`

Path generation: `mint-tsdocs.MarkdownDocumenter` → `/reference/mint-tsdocs/MarkdownDocumenter`

## Fixing Broken Links

Links break when API items are renamed, deleted, or not exported.

1. Check TypeScript error in IDE
2. Verify item exists in API reference navigation
3. Update target to correct RefId
4. Run `mint-tsdocs generate` if source changed

## Best Practices

<Check>Use RefLink for API references, PageLink for guides/concepts</Check>
<Check>Keep link text concise</Check>
<Check>Let TypeScript autocomplete guide you</Check>
<Check>Fix broken links before committing</Check>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Component not found">
    Run `mint-tsdocs generate` to copy components to `docs/snippets/tsdocs/`
  </Accordion>

  <Accordion title="All links broken">
    1. Check `ValidRefs.jsx` exists in `docs/snippets/tsdocs/`
    2. Run `mint-tsdocs generate`
    3. Refresh browser
  </Accordion>

  <Accordion title="No IDE autocomplete">
    Due to an [MDX extension bug](https://github.com/mdx-js/mdx-analyzer/issues/522), try:

    1. Use relative path while editing: `"../snippets/tsdocs/RefLink.jsx"`
    2. Get autocomplete
    3. Change back to absolute: `"/snippets/tsdocs/RefLink.jsx"`
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={3}>
  <Card title="PageLink" icon="link" href="/components/pagelink">
    Documentation page links
  </Card>

  <Card title="Link Validation" icon="shield-check" href="/components/link-validation">
    How validation works
  </Card>

  <Card title="Custom Styles" icon="palette" href="/components/custom-styles">
    Style broken links
  </Card>
</CardGroup>