allow links to be relative to site root

facebook · Apr 27, 2022 · ab51438 · ab51438
1 parent 45ed34f
commit ab51438
Show file tree

Hide file tree

Showing 3 changed files with 5 additions and 2 deletions.
diff --git a/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts b/packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts
@@ -88,6 +88,7 @@ The following operations are defined for [URI]s:
 [Relative link 2](../api/classes/divine_uri.URI.md)
 [Relative link that should be absolute](./api/classes/divine_uri.URI.md)
 [Absolute link](/api/classes/divine_uri.URI.md)
+[Absolute link from site dir](/docs/api/classes/divine_uri.URI.md)
 [Absolute link that should be relative](/another.md)
 [Relative link that acts as absolute](api/classes/divine_uri.URI.md)
 [Relative link that acts as relative](another.md)

diff --git a/packages/docusaurus-utils/src/markdownLinks.ts b/packages/docusaurus-utils/src/markdownLinks.ts
@@ -114,7 +114,7 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
       const sourcesToTry: string[] = [];
       // ./file.md and ../file.md are always relative to the current file
       if (!mdLink.startsWith('./') && !mdLink.startsWith('../')) {
-        sourcesToTry.push(...getContentPathList(contentPaths));
+        sourcesToTry.push(...getContentPathList(contentPaths), siteDir);
       }
       // /file.md is always relative to the content path
       if (!mdLink.startsWith('/')) {

diff --git a/website/docs/guides/markdown-features/markdown-features-links.md b/website/docs/guides/markdown-features/markdown-features-links.md
@@ -26,7 +26,9 @@ Reference to another [document in a subfolder](subfolder/doc3.md).
 [Relative document](../otherFolder/doc4.md) referencing works as well.
 ```
 
-Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`. Note that absolute paths are **not** resolved relative to the site directory, because that means you have to change all `/docs/` paths to their localized counterparts during localization.
+Relative file paths are resolved against the current file's directory. Absolute file paths, on the other hand, are resolved relative to the **content root**, usually `docs/`, `blog/`, or [localized ones](../../i18n/i18n-tutorial.md) like `i18n/zh-Hans/plugin-content-docs/current`.
+
+Absolute file paths can also be relative to the site directory. However, beware that links that begin with `docs/` or `blog/` are not portable as you would need to manually update them if you create new doc versions or localize them.
 
 ```md
 You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`).