How to link documentation pages effectively

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

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

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

Reference headers on the current page using the hash symbol:

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

Link to headers on other pages

Combine the page path with the anchor:

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

How Mintlify generates anchors

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

Custom anchor IDs

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

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

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:

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

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

API playground deep links

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.

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

Best practices

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.

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

Link prerequisites explicitly

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

Build topic clusters

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)

Check for broken links

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

mint broken-links

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

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.

Frequently asked questions

Related resources

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