--- title: Links & Navigation description: Link between pages, anchor to specific headings, and reference external URLs. Includes Card navigation and broken link checking. --- > **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version. 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: ```markdown 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: ```markdown 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: ```markdown 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: ```mdx Get up and running in 5 minutes ``` Get up and running in 5 minutes ### Card Groups Group related links together: ```mdx Install the CLI Configure your project ``` Install the CLI Configure your project ## Best Practices Tell readers where the link goes: ```markdown {/* Good */} Learn more in our [authentication guide](/quickstart). {/* Avoid */} For more info, [click here](/quickstart). ``` Link to the most specific relevant section: ```markdown {/* 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: ```bash 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: ```bash jamdesk broken-links ``` Example output: ```text 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: ```markdown {/* 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: ```bash 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? Improve discovery and metadata Define titles, descriptions, and SEO fields