Skip to main content
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. 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 is located. 
* [Quickstart guide](/quickstart)
* [API overview](/api-playground/overview)
* [Custom components](/customize/react-components)
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: 
[Jump to best practices](#best-practices)
Jump to best practices Combine page paths with anchor links. 
* [Customize your playground](/api-playground/overview#customize-your-playground)
* [Cards properties](/components/cards#properties)
Anchor links are automatically created from header text.
  • Convert to lowercase
  • Replace spaces with hyphens
  • Remove special characters
  • Preserve numbers and letters
Header textAnchor link
## Getting Started#getting-started
### API Authentication#api-authentication
#### Step 1: Install#step-1-install
Headers with the noAnchor prop will not generate anchor links. See Format text for details.
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. When you link to external resources, make it clear the link goes outside your documentation. 
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 what users will find when they click. 
See [Hidden pages](/organize/hidden-pages) for more information.
[Configure custom domains](/customize/custom-domain)

​
Create topic clusters

Link related content together to help users discover relevant information. 
## Related topics

- [API authentication](/api-playground/overview#authentication)
- [Adding SDK examples](/api-playground/adding-sdk-examples)
- [Managing page visibility](/api-playground/managing-page-visibility)
Add links naturally within content where they provide value. 
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 functionality.
Help users prepare by linking to prerequisite content: 
## 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
Do not create links that send users back and forth between the same pages. Use the Mintlify CLI to identify broken links in your documentation. 
mint broken-links
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. 
{
  "redirects": [
    {
      "source": "/old-path",
      "destination": "/new-path"
    }
  ]
}
See Redirects for more information.