diff --git a/changelog.mdx b/changelog.mdx
index 8de1b0a58..edbb10734 100644
--- a/changelog.mdx
+++ b/changelog.mdx
@@ -5,6 +5,14 @@ rss: true
noindex: true
---
+
+
+ ## Bug fixes
+
+ - Fixed [relative links](/guides/linking#relative-paths) (`./` and `../`) not resolving correctly in `index.mdx` files. Relative paths in index pages now resolve from the directory containing the index file rather than its parent.
+
+
+
## CLI analytics
diff --git a/guides/linking.mdx b/guides/linking.mdx
index 3b688caef..48a53e427 100644
--- a/guides/linking.mdx
+++ b/guides/linking.mdx
@@ -19,7 +19,26 @@ Link to other pages in your documentation using root-relative paths. Root-relati
- [Custom components](/customize/react-components)
```
-Avoid relative paths like `../api-playground/overview`—they break when pages move and are harder to scan during review.
+### Relative paths
+
+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 `` and `` 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`.
+
+Fragments and query strings are preserved:
+
+```mdx
+[Setup instructions](./setup#step-1)
+```
+
+
+ Root-relative paths (starting with `/`) are generally preferred for internal links because they remain correct when you move the linking page to a different directory. Use relative paths when you want links to stay valid if an entire directory subtree is moved together.
+
## Anchor links
@@ -188,7 +207,9 @@ See [Redirects](/create/redirects) for more information.
-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.
+
+Relative paths (`./` and `../`) are also supported and resolve correctly based on the source file's location. They're useful when you want links within a directory subtree to stay valid if the subtree is moved as a unit.