Links & Navigation
Link between pages, anchor to specific headings, and reference external URLs. Includes Card navigation and broken link checking.
MDX takes standard Markdown links. Jamdesk adds patterns for page links, heading anchors, and 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 open in a new tab with secure settings.
Link with Cards
Use Cards instead of inline links for prominent navigation:
<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#whats-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.
Fixing Broken Links Automatically
jamdesk fix repairs a broken link that has one unambiguous correct target (a typo'd anchor, or cross-locale anchor drift where a translated page renamed its headings):
jamdesk fix --dry-run # preview every planned fix, write nothing
jamdesk fix # apply after a y/N confirmationIt rewrites a link only when the corrected anchor is a real heading on the target page. Anything ambiguous is left for manual review. See Auto-fix broken links.
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.
Sites using hostAtDocs (docs hosted at a subpath like /docs) get the /docs prefix added to internal links at runtime. Write paths relative to your docs root:
{/* 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
Renaming a page breaks links to it. Update every reference with the CLI:
jamdesk rename api/old-name.mdx api/new-name.mdxThis command:
- Renames the file
- Updates
docs.jsonnavigation - Fixes links in all other pages