refactor: normalize Markdown linkification behavior, elaborate in doc…

…umentation

packages/docusaurus-plugin-content-docs/src/markdown/__tests__/linkify.test.ts

@@ -75,7 +75,7 @@ const sourceToPermalink: SourceToPermalink = {
 
   '@site/i18n/fr/docusaurus-plugin-content-docs/current/doc-localized.md':
     '/fr/doc-localized',
-  '@site/docs/doc-localized': '/doc-localized',
+  '@site/docs/doc-localized.md': '/doc-localized',
 };
 
 function createMarkdownOptions(

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

@@ -134,3 +134,35 @@ 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 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,35 @@ 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 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));
+      }
+      // /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]);
 

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

@@ -0,0 +1,47 @@
+---
+id: links
+description: Links to other pages in Markdown
+slug: /markdown-features/links
+---
+
+# Markdown links
+
+There are two ways of adding a link to another page: through a **URL path** and a **file path**.
+
+```md
+[URL path to another document](./installation) [file path to another document](./installation.md)
+```
+
+URL paths are unprocessed by Docusaurus, and you can see them as directly rendering to `<a href="./installation">`, i.e. it will be resolved according to the page's URL location, rather than its file-system location.
+
+If you want to reference another Markdown file **included by the same plugin**, you could use the relative path of the document you want to link to. Docusaurus' Markdown loader will convert the file path to the target file's URL path (and hence remove the `.md` extension).
+
+For example, if you are in `docs/folder/doc1.md` and you want to reference `docs/folder/doc2.md`, `docs/folder/subfolder/doc3.md` and `docs/otherFolder/doc4.md`:
+
+```md title="docs/folder/doc1.md"
+I am referencing a [document](doc2.md).
+
+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.
+
+```md
+You can write [links](/otherFolder/doc4.md) relative to the content root (`/docs/`).
+```
+
+Using relative _file_ paths (with `.md` extensions) instead of relative _URL_ links provides the following benefits:
+
+- Links will keep working on the GitHub interface and many Markdown editors
+- You can customize the files' slugs without having to update all the links
+- Moving files around the folders can be tracked by your editor, and some editors may automatically update file links
+- A [versioned doc](../docs/versioning.md) will link to another doc of the exact same version
+- Relative URL links are very likely to break if you update the [`trailingSlash` config](../../api/docusaurus.config.js.md#trailing-slash)
+
+:::warning
+
+Markdown file references only work when the source and target files are processed by the same plugin instance. This is a technical limitation of our Markdown processing architecture and will be fixed in the future. If you are linking files between plugins (e.g. linking to a doc page from a blog post), you have to use URL links.
+
+:::

website/sidebars.js

@@ -61,7 +61,6 @@ const sidebars = {
               ],
             },
             'guides/docs/versioning',
-            'guides/docs/markdown-features',
             'guides/docs/multi-instance',
           ],
         },
@@ -81,6 +80,7 @@ const sidebars = {
             'guides/markdown-features/headings',
             'guides/markdown-features/inline-toc',
             'guides/markdown-features/assets',
+            'guides/markdown-features/links',
             'guides/markdown-features/plugins',
             'guides/markdown-features/math-equations',
             'guides/markdown-features/head-metadata',