Document relative link resolution in MDX files

guides/linking.mdx

@@ -19,7 +19,24 @@
 - [Custom components](/customize/react-components)
 ```
 
-Avoid relative paths like `../api-playground/overview`—they break when pages move and are harder to scan during review.
+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.
+
+```mdx
+- [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.
+
+```mdx
+[Setup instructions](./setup#step-1)
+```
+
+<Tip>
+  Root-relative paths (starting with `/`) perform better for internal links because they remain correct if you move the linking page to a different directory.
+</Tip>
 
 ## Anchor links
 
@@ -125,7 +142,7 @@
 
 ### Link prerequisites explicitly
 
 When a page assumes prior steps, link to them at the top rather than assuming users will find them:
 
 ```mdx
 ## Prerequisites
@@ -139,7 +156,7 @@
 
 ### Build topic clusters
 
 Link related content together to help users—and search engines—understand how your documentation is organized:
 
 ```mdx
 ## Related topics
@@ -188,7 +205,9 @@
 
 <AccordionGroup>
 <Accordion title="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.
+Root-relative paths (starting with `/`) are the most common 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.
+
+You can use relative paths (`./` and `../`), but because they resolve based on the source file's location they may break more frequently.
 </Accordion>
 
 <Accordion title="How do I keep anchor links stable when I update headings?">
@@ -196,7 +215,7 @@
 </Accordion>
 
 <Accordion title="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.
 </Accordion>
 
 <Accordion title="How many internal links should a page have?">