Add linking and references guide

docs.json

@@ -285,6 +285,7 @@
                   "guides/content-templates",
                   "guides/improving-docs",
                   "guides/internationalization",
+                  "guides/linking",
                   "guides/maintenance",
                   "guides/media",
                   "guides/navigation",

guides/index.mdx

@@ -30,9 +30,10 @@
 
 - [Accessibility](/guides/accessibility): Make your docs accessible to as many users as possible.
 - [Content types](/guides/content-types): Choose the right format for tutorials, how-tos, references, and explanations.
 - [Content templates](/guides/content-templates): Copy and modify templates for each content type.
 - [Improve your docs](/guides/improving-docs): Use data and feedback to continuously improve your documentation.
 - [Internationalization](/guides/internationalization): Set up multi-language documentation to reach global audiences.
+- [Linking](/guides/linking): Create internal links, reference API endpoints, and maintain link integrity across your documentation.
 - [Maintenance](/guides/maintenance): Keep your documentation accurate and up-to-date.
 - [Media](/guides/media): Add images, videos, and other media effectively while managing maintenance burden.
 - [Organize navigation](/guides/navigation): Design information architecture that works for your users.

guides/linking.mdx

@@ -0,0 +1,185 @@
+---
+title: "Linking"
+description: "Learn how to create internal links, reference API endpoints, and maintain link integrity across your documentation."
+keywords: ["internal links", "cross-references", "anchor links", "broken links"]
+---
+
+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.
+
+## 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 is located.
+
+```mdx
+* [Quickstart guide](/quickstart)
+* [API overview](/api-playground/overview)
+* [Custom components](/customize/react-components)
+```
+
+* [Quickstart guide](/quickstart)
+* [API overview](/api-playground/overview)
+* [Custom components](/customize/react-components)
+
+## Anchor links
+
+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:
+
+```mdx
+[Jump to best practices](#best-practices)
+```
+
+[Jump to best practices](#best-practices)
+
+### Link to headers on other pages
+
+Combine page paths with anchor links.
+
+```mdx
+* [Customize your playground](/api-playground/overview#customize-your-playground)
+* [Cards properties](/components/cards#properties)
+```
+
+* [Customize your playground](/api-playground/overview#customize-your-playground)
+* [Cards properties](/components/cards#properties)
+
+### How anchor links are generated
+
+Anchor links are automatically created from header text.
+
+* Convert to lowercase
+* Replace spaces with hyphens
+* Remove special characters
+* Preserve numbers and letters
+
+| Header text | Anchor link |
+|-------------|-------------|
+| `## Getting Started` | `#getting-started` |
+| `### API Authentication` | `#api-authentication` |
+| `#### Step 1: Install` | `#step-1-install` |
+
+<Note>
+  Headers with the `noAnchor` prop will not generate anchor links. See [Format text](/create/text#disabling-anchor-links) for details.
+</Note>
+
+## Link to API endpoints
+
+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.
+
+
+## Link to external pages
+
+When you link to external resources, make it clear the link goes outside your documentation.
+
+```mdx
+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.
+
+<CodeGroup>
+
+```mdx Good examples
+See [Hidden pages](/organize/hidden-pages) for more information.
+[Configure custom domains](/customize/custom-domain)
+```
+
+```mdx Avoid
+[Click here](/api-playground/overview)
+[Read more](/deploy/deployments)
+[See this page](/customize/custom-domain)
+```
+
+</CodeGroup>
+
+### Create topic clusters
+
+Link related content together to help users discover relevant information.
+
+```mdx
+## Related topics
+
+- [API authentication](/api-playground/overview#authentication)
+- [Adding SDK examples](/api-playground/adding-sdk-examples)
+- [Managing page visibility](/api-playground/managing-page-visibility)
+```
+
+### Use contextual links
+
+Add links naturally within content where they provide value.
+
+```mdx
+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.
+```
+
+### Link to prerequisites
+
+Help users prepare by linking to prerequisite content:
+
+```mdx
+## 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
+```
+
+### Avoid circular links
+
+Do not create links that send users back and forth between the same pages.
+
+### Check for broken links
+
+Use the Mintlify CLI to identify broken links in your documentation.
+
+```bash
+mint broken-links
+```
+
+### Update links when reorganizing
+
+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.
+2. Search your documentation for references to the old path.
+3. Update all internal links to use the new path.
+4. Run `mint broken-links` to verify all links work.
+
+### Use redirects for moved content
+
+When permanently moving content, add redirects to prevent broken links.
+
+```json
+{
+  "redirects": [
+    {
+      "source": "/old-path",
+      "destination": "/new-path"
+    }
+  ]
+}
+```
+
+See [Redirects](/create/redirects) for more information.
+
+## Related resources
+
+- [Format text](/create/text): Learn about Markdown formatting.
+- [Navigation](/organize/navigation): Configure your documentation structure.
+- [Redirects](/create/redirects): Set up redirects for moved content.