refactor: normalize Markdown linkification behavior, elaborate in documentation (#7248)

* refactor: normalize Markdown linkification behavior, elaborate in documentation

* fix broken links

* allow links to be relative to site root

* fix test

* minor doc update

* Update website/docs/guides/markdown-features/markdown-features-links.md

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

packages/docusaurus-utils/src/__tests__/__snapshots__/markdownLinks.test.ts.snap

@@ -134,3 +134,36 @@ The following operations are defined for [URI]s:
       ",
 }
 `;
+
+exports[`replaceMarkdownLinks resolves absolute and relative links differently 1`] = `
+{
+  "brokenMarkdownLinks": [
+    {
+      "contentPaths": {
+        "contentPath": "docs",
+        "contentPathLocalized": "i18n/docs-localized",
+      },
+      "filePath": "docs/intro/intro.md",
+      "link": "./api/classes/divine_uri.URI.md",
+    },
+    {
+      "contentPaths": {
+        "contentPath": "docs",
+        "contentPathLocalized": "i18n/docs-localized",
+      },
+      "filePath": "docs/intro/intro.md",
+      "link": "/another.md",
+    },
+  ],
+  "newContent": "
+[Relative link](/docs/another)
+[Relative link 2](/docs/api/classes/uri)
+[Relative link that should be absolute](./api/classes/divine_uri.URI.md)
+[Absolute link](/docs/api/classes/uri)
+[Absolute link from site dir](/docs/api/classes/uri)
+[Absolute link that should be relative](/another.md)
+[Relative link that acts as absolute](/docs/api/classes/uri)
+[Relative link that acts as relative](/docs/another)
+",
+}
+`;

packages/docusaurus-utils/src/__tests__/markdownLinks.test.ts

@@ -67,6 +67,36 @@ The following operations are defined for [URI]s:
     ).toMatchSnapshot();
   });
 
+  it('resolves absolute and relative links differently', () => {
+    expect(
+      replaceMarkdownLinks({
+        siteDir: '.',
+        filePath: 'docs/intro/intro.md',
+        contentPaths: {
+          contentPath: 'docs',
+          contentPathLocalized: 'i18n/docs-localized',
+        },
+
+        sourceToPermalink: {
+          '@site/docs/intro/intro.md': '/docs/intro',
+          '@site/docs/intro/another.md': '/docs/another',
+          '@site/docs/api/classes/divine_uri.URI.md': '/docs/api/classes/uri',
+        },
+
+        fileString: `
+[Relative link](./another.md)
+[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)
+`,
+      }),
+    ).toMatchSnapshot();
+  });
+
   // TODO bad
   it('ignores links in HTML comments', () => {
     expect(

packages/docusaurus-utils/src/markdownLinks.ts

@@ -111,12 +111,18 @@ export function replaceMarkdownLinks<T extends ContentPaths>({
       // Replace it to correct html link.
       const mdLink = mdMatch.groups!.filename!;
 
-      const sourcesToTry = [
-        path.dirname(filePath),
-        ...getContentPathList(contentPaths),
-      ].map((p) => path.join(p, decodeURIComponent(mdLink)));
+      const sourcesToTry: string[] = [];
+      // ./file.md and ../file.md are always relative to the current file
+      if (!mdLink.startsWith('./') && !mdLink.startsWith('../')) {
+        sourcesToTry.push(...getContentPathList(contentPaths), siteDir);
+      }
+      // /file.md is always relative to the content path
+      if (!mdLink.startsWith('/')) {
+        sourcesToTry.push(path.dirname(filePath));
+      }
 
       const aliasedSourceMatch = sourcesToTry
+        .map((p) => path.join(p, decodeURIComponent(mdLink)))
         .map((source) => aliasedSitePath(source, siteDir))
         .find((source) => sourceToPermalink[source]);