Links in MDX

Links are the connective tissue of the web. They connect your pages to each other, point readers to external resources, and enable navigation within long documents. In MDX, links use standard Markdown syntax — if you know text, you already know the basics. But there are many patterns, best practices, and MDX-specific considerations that will make your links more effective, accessible, and maintainable.

External Links

Links to other websites use the full URL including the protocol:

Always include https:// at the beginning. Without the protocol, the link will be treated as a relative path on your own site, leading to a 404 error.

Best practice for external links: In documentation sites, external links should typically open in a new tab so readers do not lose their place in your docs. Standard Markdown does not support target="_blank", so in MDX you use an HTML anchor tag:

The rel="noopener noreferrer" attribute is a security best practice. Without it, the linked page can access your page through window.opener, which creates a potential security vulnerability.

Internal Links

Links to other pages on your own site use relative paths:

Why relative paths matter: They work correctly across environments. The same relative link works on localhost during development, on a staging server, and in production — regardless of the domain name. Absolute URLs (with the full domain) would break when moving between environments.

In Next.js, internal links written this way work like <Link> components — they perform client-side navigation without a full page reload. The page transitions feel instant because only the new content is fetched, not the entire HTML document.

Path conventions:

• ./page — page in the same directory
• ../page — page in the parent directory
• /docs/page — absolute path from the site root
• ../../other/page — navigating up two levels then into another folder

Anchor Links (Jump to Section)

Link to a specific heading on the same page using a # followed by the heading's ID:

The anchor ID is generated from the heading text: lowercase, spaces replaced with hyphens, special characters removed. So a heading ## Installation Guide gets the ID installation-guide.

You can also link to a heading on a different page:

This navigates to the setup page and automatically scrolls to the "Configuration options" section.

Links with Titles (Tooltips)

Add a title that appears as a tooltip on hover:

The title text goes inside quotes after the URL. It appears as a browser tooltip when users hover over the link. This is useful for providing additional context without cluttering the visible text, but do not rely on it for critical information since mobile users cannot hover.

Image Links

Make an image clickable by wrapping image syntax inside link syntax:

The outer []() is the link. The inner ![]() is the image. This pattern is commonly used for:

• Logos that link to homepages
• Thumbnails that link to videos
• Screenshots that link to live demos
• Badges that link to CI/CD status pages

Email and Phone Links

Special URL schemes enable email and phone links:

The mailto: scheme opens the user's default email client. You can even pre-fill the subject line using URL parameters. The tel: scheme triggers the phone dialer on mobile devices.

Reference-Style Links

For documents with many links, reference-style syntax keeps your prose clean and readable:

Define links at the bottom of your file and reference them by label in the text. This approach offers several advantages:

• Readable prose — the text flows naturally without long URLs interrupting
• Easy maintenance — update a URL in one place and all references update
• Reduced errors — repeated URLs only need to be typed once
• Clean diffs — changing a URL shows as a single line change in Git

Automatic URL Detection

Some MDX configurations automatically make bare URLs clickable:

However, this behavior depends on your MDX configuration and plugins. Being explicit with text syntax is always safer and gives you control over the link text.

Links in MDX with React Components

Because MDX supports JSX, you can also use React link components:

This is useful when you need framework-specific link behavior like prefetching, scroll restoration, or custom active states. However, for most content, standard Markdown link syntax is simpler and more portable.

Accessibility Best Practices for Links

Writing accessible links is crucial for users who rely on screen readers:

1. Link text must describe the destination. Screen readers can navigate a page by listing all links. If every link says "click here" or "read more", the list is useless.

2. Avoid generic phrases as link text. "Click here", "read more", "learn more", and "this page" tell users nothing about where the link goes.

3. Keep link text concise. Two to five words is ideal. Links that are entire sentences are hard to scan.

4. Indicate external links. Adding "(opens in new tab)" or a visual icon helps users understand they are leaving your site.

5. Do not use URLs as link text. https://very-long-url.example.com/path/to/page is not useful to screen reader users.

Common Mistakes

Quick Reference