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.
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 Combine page paths with anchor links.
Anchor links are automatically created from header text.
  • Convert to lowercase
  • Replace spaces with hyphens
  • Remove special characters
  • Preserve numbers and letters
Headers with the noAnchor prop do 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.

​
Best practices

​
Write descriptive link text

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

​
Create topic clusters

Link related content together to help users discover relevant information.
Add links naturally within content where they provide value.
Help users prepare by linking to prerequisite content:
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.
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.
See Redirects for more information.