From 5da227efb09f2c8d136b089ecf204544700c66cd Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Wed, 15 Apr 2026 16:27:09 +0000 Subject: [PATCH 1/5] Document relative link resolution support and changelog entry Generated-By: mintlify-agent --- changelog.mdx | 8 ++++++++ guides/linking.mdx | 25 +++++++++++++++++++++++-- 2 files changed, 31 insertions(+), 2 deletions(-) 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. From 9128fe91056f0d5e73378320ea3c4d14dab55509 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 24 Apr 2026 10:50:42 -0700 Subject: [PATCH 2/5] Apply suggestion from @ethanpalm --- changelog.mdx | 8 -------- 1 file changed, 8 deletions(-) diff --git a/changelog.mdx b/changelog.mdx index edbb10734..8de1b0a58 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -5,14 +5,6 @@ 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 From 45c505f5cafb3efbfd20b670123f22e081b76130 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 24 Apr 2026 10:52:03 -0700 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> --- guides/linking.mdx | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/guides/linking.mdx b/guides/linking.mdx index 48a53e427..dcec60fda 100644 --- a/guides/linking.mdx +++ b/guides/linking.mdx @@ -19,8 +19,6 @@ Link to other pages in your documentation using root-relative paths. Root-relati - [Custom components](/customize/react-components) ``` -### 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 @@ -30,7 +28,7 @@ Mintlify resolves relative paths (`./` and `../`) based on the source file's loc 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: +Links preserve fragments and query strings. ```mdx [Setup instructions](./setup#step-1) From 1af20f0980a5057d592e146487e95868964a8d53 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 24 Apr 2026 10:53:15 -0700 Subject: [PATCH 4/5] Apply suggestion from @ethanpalm --- guides/linking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/linking.mdx b/guides/linking.mdx index dcec60fda..70aeecb51 100644 --- a/guides/linking.mdx +++ b/guides/linking.mdx @@ -35,7 +35,7 @@ Links preserve fragments and query strings. ``` - 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. + Root-relative paths (starting with `/`) perform better for internal links because they remain correct if you move the linking page to a different directory. ## Anchor links From 8b5e11cddc7f0ef0a15d03f9df767212b1409eb0 Mon Sep 17 00:00:00 2001 From: Ethan Palm <56270045+ethanpalm@users.noreply.github.com> Date: Fri, 24 Apr 2026 10:54:51 -0700 Subject: [PATCH 5/5] Apply suggestion from @ethanpalm --- guides/linking.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/linking.mdx b/guides/linking.mdx index 70aeecb51..d50b3782a 100644 --- a/guides/linking.mdx +++ b/guides/linking.mdx @@ -207,7 +207,7 @@ See [Redirects](/create/redirects) for more information. 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. +You can use relative paths (`./` and `../`), but because they resolve based on the source file's location they may break more frequently.