Links & Navigation

Links are the backbone of documentation. They connect related concepts, guide readers through workflows, and reference external resources.

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="Quick Start" icon="rocket" href="/quickstart">

  Get up and running in 5 minutes

</Card>

Quick Start

Get up and running in 5 minutes

Card Groups

Group related links together:

<CardGroup 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>
</CardGroup>

Installation

Install the CLI

Configuration

Configure your project

Best Practices

Tell readers where the link goes:

{/* Good */}
Learn more in our [authentication guide](/auth).

{/* Avoid */}
For more info, [click here](/auth).

Link to the most specific relevant section:

{/* Good - links to specific section */}
Configure [OAuth settings](/auth#oauth-configuration).

{/* Less helpful - links to entire page */}
See the [auth docs](/auth) for OAuth settings.

Broken links frustrate readers. Run link checks regularly:

jamdesk broken-links

This scans your docs and reports any broken internal links.

Checking for Broken Links

The Jamdesk CLI can scan for broken links:

jamdesk broken-links

Example 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.

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.mdx

This automatically:

Renames the file
Updates docs.json navigation
Fixes links in all other pages

What's Next?

Navigation Structure

Organize your sidebar

Card Component

Create visual navigation