# How to link documentation pages effectively (/guides/linking)

<!-- agent-signals: reading_time_min: 6 · est_tokens: 2431 · updated: 2026-07-30 -->
Related: [How to create accessible documentation](/guides/accessibility.md), [Documentation content templates](/guides/content-templates.md), [Documentation content types](/guides/content-types.md), [Headless docs with a custom frontend](/guides/custom-frontend.md), [Build custom page layouts](/guides/custom-layouts.md), [Create developer documentation](/guides/developer-documentation.md)

Links connect your documentation into a coherent system. They help users discover related content, navigate efficiently, and follow a logical path through complex topics. Poor links—vague anchor text, missing cross-references, broken URLs—make documentation harder to use and hurt SEO.

This guide covers how to create different types of links in Mintlify and how to maintain link integrity as your documentation grows.

## Internal links [#internal-links]

Link to other pages in your documentation using root-relative paths. Root-relative paths start from the root of your documentation directory and work consistently regardless of where the linking page sits in your directory structure.

```mdx
- [Quickstart guide](/quickstart)
- [API overview](/api-playground/overview)
- [Custom components](/customize/react-components)
```

Mintlify resolves relative paths (`./` and `../`) based on the source file's location in your project directory. This works for links, images, and JSX elements like `<Card>` and `<a>` tags.

```mdx
- [Sibling page](./sibling-page)
- [Parent section page](../other-page)
```

For `index.mdx` files, relative paths resolve from the directory that contains the index file. For example, a `./setup` link in `guides/getting-started/index.mdx` resolves to `/guides/getting-started/setup`.

Links preserve fragments and query strings.

```mdx
[Setup instructions](./setup#step-1)
```

<Tip>
  Root-relative paths (starting with `/`) perform better for internal links because they remain correct if you move the linking page to a different directory.
</Tip>

## Anchor links [#anchor-links]

Anchor links point to specific sections within a page. Every heading automatically generates an anchor based on its text.

### Link to headers on the same page [#link-to-headers-on-the-same-page]

Reference headers on the current page using the hash symbol:

```mdx
[Jump to best practices](#best-practices)
```

### Link to headers on other pages [#link-to-headers-on-other-pages]

Combine the page path with the anchor:

```mdx
- [Customize your playground](/api-playground/overview#customize-your-playground)
- [Cards properties](/components/cards#properties)
```

### How Mintlify generates anchors [#how-mintlify-generates-anchors]

Mintlify automatically creates anchors from header text by converting to lowercase, replacing spaces with hyphens, and removing special characters.

| Header text              | Generated anchor      |
| ------------------------ | --------------------- |
| `## Getting Started`     | `#getting-started`    |
| `### API Authentication` | `#api-authentication` |
| `#### Step 1: Install`   | `#step-1-install`     |

<Note>
  Headers with the `noAnchor` prop do not generate anchor links. See [Format text](/create/text#disable-anchor-links) for details.
</Note>

### Custom anchor IDs [#custom-anchor-ids]

Override the auto-generated anchor for any heading by appending `{#custom-id}` to the header text:

```mdx
## Configuration options [#config]
```

This heading is reachable at `#config` instead of `#configuration-options`. Custom IDs keep anchor links stable when you update heading text—useful for headings you link to frequently. See [Format text](/create/text#custom-heading-ids) for more details.

## Deep links [#deep-links]

Deep links point to specific states or locations within a page, not just the page itself.

### Accordion deep links [#accordion-deep-links]

When a user opens an accordion, the URL hash updates to reflect the open state. Visiting a URL with that hash automatically opens and scrolls to the accordion.

By default, the hash derives from the accordion's `title`. Use the `id` property to set a custom hash:

```mdx
<Accordion title="Installation steps" id="install">
  ...
</Accordion>
```

This accordion is reachable at `#install` instead of the auto-generated `#installation-steps`. See [Accordions](/components/accordions) for more.

### API playground deep links [#api-playground-deep-links]

To open the API playground in a link, append `?playground=open` to any endpoint page URL:

```text
https://your-docs-url/endpoint-path?playground=open
```

The URL updates as users open or close the playground. Use playground deep links in support conversations or onboarding flows to send users directly to an endpoint's interactive playground. See [API playground](/api-playground/overview#parameter-anchor-links) for information on parameter anchor links.

## External links [#external-links]

When linking to external resources, write anchor text that makes the destination clear:

```mdx
See the [OpenAPI specification](https://swagger.io/specification/) in the Swagger documentation for details.
```

## Best practices [#best-practices]

### Write descriptive anchor text [#write-descriptive-anchor-text]

Anchor text should tell users where they're going before they click. Vague phrases like "click here" or "read more" are also weaker SEO signals than descriptive text.

<CodeGroup>
  <CodeBlockTabs defaultValue="Good" groupId="avoid+good">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Good">
        Good
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Avoid">
        Avoid
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Good">
      ```mdx  
      See [Hidden pages](/organize/hidden-pages) for more information.
      [Configure custom domains](/customize/custom-domain)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Avoid">
      ```mdx  
      [Click here](/api-playground/overview)
      [Read more](/deploy/deployments)
      [See this page](/customize/custom-domain)
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

### Link prerequisites explicitly [#link-prerequisites-explicitly]

When a page assumes prior steps, link to them at the top rather than assuming users find them:

```mdx
## Prerequisites

Before deploying your documentation, ensure you have:

- Completed the [quickstart guide](/quickstart)
- Configured your [custom domain](/customize/custom-domain)
- Set up [authentication](/deploy/authentication-setup) if needed
```

### Build topic clusters [#build-topic-clusters]

Link related content together to help users—and search engines—understand how you organize your content:

```mdx
## Related topics

- [API authentication](/api-playground/overview#authentication)
- [Adding SDK examples](/api-playground/adding-sdk-examples)
- [Managing page visibility](/api-playground/managing-page-visibility)
```

### Check for broken links [#check-for-broken-links]

Run the Mintlify CLI before publishing to catch broken internal and external links:

```bash
mint broken-links
```

### Update links when reorganizing [#update-links-when-reorganizing]

When moving or renaming pages:

1. Update the page path in your navigation configuration.
2. Configure redirects from the old path to the new path.
3. Search your documentation for references to the old path.
4. Update all internal links to use the new path.
5. Run `mint broken-links` to verify.

### Use redirects for moved content [#use-redirects-for-moved-content]

When permanently moving content, add redirects to prevent broken links for users who have bookmarked or shared old URLs.

```json
{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path"
    }
  ]
}
```

See [Redirects](/create/redirects) for more information.

## Frequently asked questions [#frequently-asked-questions]

<AccordionGroup>
  <Accordion title="Should I use root-relative or absolute URLs for internal links?">
    Root-relative paths (starting with `/`) are the most common choice for internal links in Mintlify. They work consistently regardless of where the linking page sits in your directory, and they don't break if your documentation domain changes. Absolute URLs for internal links create unnecessary brittleness.

    You can use relative paths (`./` and `../`), but because they resolve based on the source file's location they may break more frequently.
  </Accordion>

  <Accordion title="How do I keep anchor links stable when I update headings?">
    Use custom anchor IDs for headings you link to frequently. Appending `{#custom-id}` to a heading decouples the anchor from the heading text, so you can update the heading text without breaking any links that point to it. This is especially useful for headings in high-traffic reference sections where the text may need refinement over time.
  </Accordion>

  <Accordion title="What happens to bookmarked links when I reorganize my documentation?">
    Bookmarked and shared links become 404 errors without redirects. Set up redirects in your `docs.json` whenever you move or rename a page. Redirects are cheap to add and prevent a poor user experience for anyone who linked to your documentation from an external source—blog posts, Stack Overflow answers, internal wikis.
  </Accordion>

  <Accordion title="How many internal links should a page have?">
    Link whenever a related concept is genuinely useful to the user in that moment—not to meet a quota. Too few links leave users without context or next steps. Too many links turn the page into a navigation exercise that pulls users away from what they're trying to do. As a rough heuristic, link the first mention of a concept or tool, and don't repeat the same link multiple times on a single page.
  </Accordion>
</AccordionGroup>

## Related resources [#related-resources]

* [Format text](/create/text): Markdown formatting options including heading IDs and anchor behavior.
* [Navigation](/organize/navigation): Configure your documentation structure.
* [Redirects](/create/redirects): Set up redirects for moved content.