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.

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)

Avoid relative paths like ../api-playground/overview—they break when pages move and are harder to scan during review.

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.

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

Headers with the noAnchor prop do not generate anchor links. See Format text for details.

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.

Good

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 will 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 your documentation is organized:

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

Should I use root-relative or absolute URLs for internal links?

Root-relative paths (starting with /) are the right 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.

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.

What happens to bookmarked links when I reorganize my documentation?

Without redirects, bookmarked and shared links become 404 errors. 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.

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.

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.