Links & Navigation
Link between pages, anchor to specific headings, and reference external URLs. Includes Card navigation and broken link checking.
MDX supports standard Markdown links plus Jamdesk-specific patterns for linking between pages, anchoring to headings, and referencing external URLs.
Internal Links
Link to other pages in your docs using relative paths:
Read the [getting started guide](/quickstart) first.
See the [Card component](/components/card) for more options.Use paths relative to your docs root, without the .mdx extension.
Link to Headings
Link directly to a section using anchor links:
See [configuration options](/config/docs-json-reference#colors)Headings automatically generate anchors from their text:
## Getting Started→#getting-started## API Reference→#api-reference
External Links
Link to external sites:
Check the [GitHub repository](https://github.com/example/repo).External links automatically open in a new tab with secure settings.
Link with Cards
For prominent navigation, use Cards instead of inline links:
<Card title="Quickstart" icon="rocket" href="/quickstart">
Get up and running in 5 minutes
</Card>Card Groups
Group related links together:
<Columns cols={2}>
<Card title="Installation" icon="download" href="/cli/overview">
Install the CLI
</Card>
<Card title="Configuration" icon="gear" href="/config/docs-json-reference">
Configure your project
</Card>
</Columns>Best Practices
Tell readers where the link goes:
{/* Good */}
Learn more in our [authentication guide](/quickstart).
{/* Avoid */}
For more info, [click here](/quickstart).Link to the most specific relevant section:
{/* Good - links to specific section */}
Configure [OAuth settings](/quickstart#what-s-next).
{/* Less helpful - links to entire page */}
See the [auth docs](/quickstart) for OAuth settings.Broken links frustrate readers. Run link checks regularly:
jamdesk broken-linksThis scans your docs and reports any broken internal links.
Checking for Broken Links
The Jamdesk CLI can scan for broken links:
jamdesk broken-linksExample output:
docs/getting-started.mdx:15 - /docs/quikstart
Did you mean: /docs/quickstart
Found 1 broken link in 45 files.
Run this before deploying to catch typos and outdated references.
How Internal Links Are Detected
Links without https:// are treated as internal and validated against your docs pages. The validator checks that the target page exists in your docs.json navigation.
For sites using hostAtDocs (docs hosted at a subpath like /docs), internal links are automatically prefixed at runtime. Write paths relative to your docs root — the /docs prefix is added for you:
{/* Just write the docs path — auto-prefixed to /docs/config/docs-json-reference */}
See the [Reference](/config/docs-json-reference).Non-docs links (like marketing pages) should use full URLs: https://example.com/pricing.
Any /path link in your docs content is treated as an internal docs link.
Renaming Pages
When you rename a page, links break. Use the CLI to update all references:
jamdesk rename api/old-name.mdx api/new-name.mdxThis automatically:
- Renames the file
- Updates
docs.jsonnavigation - Fixes links in all other pages