How to link documentation pages effectively

Create internal links, anchor links, and deep links in your documentation, and maintain link integrity with redirects and broken link checks.

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.

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.

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

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

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

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

Reference headers on the current page using the hash symbol:

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

Combine the page path with the anchor:

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

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

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

## 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 for more details.

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

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:

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

This accordion is reachable at #install instead of the auto-generated #installation-steps. See Accordions for more.

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

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 for information on parameter anchor links.

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

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

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.

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

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

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

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

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

## Related topics

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

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

mint broken-links

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.

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

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

See Redirects for more information.

• Format text: Markdown formatting options including heading IDs and anchor behavior.
• Navigation: Configure your documentation structure.
• Redirects: Set up redirects for moved content.

• How to improve documentation SEO
• How to measure and improve documentation quality
• Guides