mintlify__docs/guides/linking.mdx

---
title: "Linking"
description: "Learn how to create internal links, reference API endpoints, and maintain link integrity across your documentation."
keywords: ["internal links", "cross-references", "anchor links", "broken links", "deep linking", "custom heading IDs"]
---

Effective linking creates a connected documentation experience that helps users discover related content and navigate efficiently. Too many links or broken links can confuse users and make your documentation less effective. This guide covers how to create and maintain links throughout your documentation.

## 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 pages are in your directory.

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

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

## Anchor links

Anchor links allow you to link directly to specific sections within a page. Every header automatically generates an anchor link based on its text.

### Link to headers on the same page

Reference headers on the current page using the hash symbol:

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

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

### Link to headers on other pages

Combine page paths with anchor links.

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

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

### How Mintlify generates anchor links

Mintlify automatically creates anchor links from header text.

* Convert to lowercase
* Replace spaces with hyphens
* Remove special characters
* Preserve numbers and letters

| Header text | Anchor link |
|-------------|-------------|
| `## 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#disabling-anchor-links) for details.
</Note>

### Custom anchor IDs

You can 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 are useful for keeping anchor links stable when you update heading text. See [Format text](/create/text#custom-heading-ids) for more details.

## Deep linking

Deep links point to specific states or locations within a page, not just the page itself. Use deep links to send users directly to an open accordion or an API playground view.

### 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 information.

### 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 to share a direct link to an endpoint's interactive playground in support conversations or onboarding flows.

See [API playground](/api-playground/overview#parameter-anchor-links) for information on parameter anchor links.

## Link to API endpoints

When documenting APIs, you can link to specific endpoints from anywhere in your documentation.

Link to API endpoint pages using their path in the navigation.


## Link to external pages

When you link to external resources, make it clear the link goes outside your documentation.

```mdx
Learn more about [Markdown syntax](https://www.markdownguide.org/) (external link).

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

## Best practices

### Write descriptive link text

Use clear, descriptive text that indicates where a link takes users.

<CodeGroup>

```mdx Good examples
See [Hidden pages](/organize/hidden-pages) for more information.
[Configure custom domains](/customize/custom-domain)
```

```mdx Avoid
[Click here](/api-playground/overview)
[Read more](/deploy/deployments)
[See this page](/customize/custom-domain)
```

</CodeGroup>

### Create topic clusters

Link related content together to help users discover relevant information.

```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)
```

### Use contextual links

Add links naturally within content where they provide value.

```mdx
To customize your documentation appearance, configure [themes](/customize/themes) 
and [fonts](/customize/fonts) in your settings. You can also add 
[custom scripts](/customize/custom-scripts) for advanced features.
```

### Link to prerequisites

Help users prepare by linking to prerequisite content:

```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
```

### Avoid circular links

Do not create links that send users back and forth between the same pages.

### Check for broken links

Use the Mintlify CLI to identify broken links in your documentation.

```bash
mint broken-links
```

### Update links when reorganizing

When moving or renaming pages:

1. Update the page path in your navigation configuration.
2. Configure redirects for 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 all links work.

### Use redirects for moved content

When permanently moving content, add redirects to prevent broken links.

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

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

## Related resources

- [Format text](/create/text): Learn about Markdown formatting.
- [Navigation](/organize/navigation): Configure your documentation structure.
- [Redirects](/create/redirects): Set up redirects for moved content.