diff --git a/guides/linking.mdx b/guides/linking.mdx index 3b688caef..d50b3782a 100644 --- a/guides/linking.mdx +++ b/guides/linking.mdx @@ -19,7 +19,24 @@ 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. +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`. + +Links preserve fragments and query strings. + +```mdx +[Setup instructions](./setup#step-1) +``` + + + 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 @@ -188,7 +205,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. + +You can use relative paths (`./` and `../`), but because they resolve based on the source file's location they may break more frequently.