feat(pages): add support for Markdown file path links (#11666)

Co-authored-by: sebastien <lorber.sebastien@gmail.com>

Author: VedantMadane

packages/docusaurus-plugin-content-pages/src/contentHelpers.ts

@@ -0,0 +1,33 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+import type {LoadedContent, Metadata} from '@docusaurus/plugin-content-pages';
+
+function indexPagesBySource(content: LoadedContent): Map<string, Metadata> {
+  return new Map(content.map((page) => [page.source, page]));
+}
+
+// TODO this is bad, we should have a better way to do this (new lifecycle?)
+//  The source to page/permalink is a mutable map passed to the mdx loader
+//  See https://github.com/facebook/docusaurus/pull/10457
+//  See https://github.com/facebook/docusaurus/pull/10185
+export function createContentHelpers() {
+  const sourceToPage = new Map<string, Metadata>();
+  const sourceToPermalink = new Map<string, string>();
+
+  // Mutable map update :/
+  function updateContent(content: LoadedContent): void {
+    sourceToPage.clear();
+    sourceToPermalink.clear();
+    indexPagesBySource(content).forEach((value, key) => {
+      sourceToPage.set(key, value);
+      sourceToPermalink.set(key, value.permalink);
+    });
+  }
+
+  return {updateContent, sourceToPage, sourceToPermalink};
+}

packages/docusaurus-plugin-content-pages/src/index.ts

@@ -13,10 +13,12 @@ import {
   addTrailingPathSeparator,
   createAbsoluteFilePathMatcher,
   getContentPathList,
+  resolveMarkdownLinkPathname,
 } from '@docusaurus/utils';
 import {createMDXLoaderRule} from '@docusaurus/mdx-loader';
 import {createAllRoutes} from './routes';
 import {createPagesContentPaths, loadPagesContent} from './content';
+import {createContentHelpers} from './contentHelpers';
 import type {LoadContext, Plugin} from '@docusaurus/types';
 import type {
   PluginOptions,
@@ -32,6 +34,7 @@ export default async function pluginContentPages(
   const {siteConfig, siteDir, generatedFilesDir} = context;
 
   const contentPaths = createPagesContentPaths({context, options});
+  const contentHelpers = createContentHelpers();
 
   const pluginDataDirRoot = path.join(
     generatedFilesDir,
@@ -82,6 +85,14 @@ export default async function pluginContentPages(
           image: frontMatter.image,
         }),
         markdownConfig: siteConfig.markdown,
+        resolveMarkdownLink: ({linkPathname, sourceFilePath}) => {
+          return resolveMarkdownLinkPathname(linkPathname, {
+            sourceFilePath,
+            sourceToPermalink: contentHelpers.sourceToPermalink,
+            siteDir,
+            contentPaths,
+          });
+        },
       },
     });
   }
@@ -109,6 +120,7 @@ export default async function pluginContentPages(
       if (!content) {
         return;
       }
+      contentHelpers.updateContent(content);
       await createAllRoutes({content, options, actions});
     },
 

website/_dogfooding/_pages tests/index.mdx

@@ -43,3 +43,4 @@ import Readme from "../README.mdx"
 - [Embeds](/tests/pages/embeds)
 - [Style Isolation tests](/tests/pages/style-isolation)
 - [IdealImage tests](/tests/pages/ideal-image)
+- [Linking tests](./linking/index.md)

website/_dogfooding/_pages tests/linking/index.md

@@ -0,0 +1,26 @@
+---
+title: Markdown Linking Test
+description: Test pages to verify markdown file path links work in the pages plugin
+---
+
+# Linking Test
+
+This folder contains test pages to verify markdown file path links work correctly in the `@docusaurus/plugin-content-pages`.
+
+## Relative file path links
+
+- [`./index.md`](./index.md)
+- [`./page-a.md`](./page-a.md)
+- [`./nested/page-b.md`](./nested/page-b.md)
+
+## Absolute file path links
+
+- [`/index.md`](/linking/index.md)
+- [`/page-a.md`](/linking/page-a.md)
+- [`/nested/page-b.md`](/linking/nested/page-b.md)
+
+## Site alias file path links
+
+- [`@site/_dogfooding/_pages tests/linking/index.md`](<@site/_dogfooding/_pages tests/linking/index.md>)
+- [`@site/_dogfooding/_pages tests/linking/page-a.md`](<@site/_dogfooding/_pages tests/linking/page-a.md>)
+- [`@site/_dogfooding/_pages tests/linking/nested/page-b.md`](<@site/_dogfooding/_pages tests/linking/nested/page-b.md>)

website/_dogfooding/_pages tests/linking/nested/page-b.md

@@ -0,0 +1,20 @@
+# Linking Test - Page B
+
+## Relative file path links
+
+- [`../index.md`](../index.md)
+- [`../page-a.md`](../page-a.md)
+- [`./page-b.md`](./page-b.md)
+- [`../nested/page-b.md`](../nested/page-b.md)
+
+## Absolute file path links
+
+- [`/index.md`](/linking/index.md)
+- [`/page-a.md`](/linking/page-a.md)
+- [`/nested/page-b.md`](/linking/nested/page-b.md)
+
+## Site alias file path links
+
+- [`@site/_dogfooding/_pages tests/linking/index.md`](<@site/_dogfooding/_pages tests/linking/index.md>)
+- [`@site/_dogfooding/_pages tests/linking/page-a.md`](<@site/_dogfooding/_pages tests/linking/page-a.md>)
+- [`@site/_dogfooding/_pages tests/linking/nested/page-b.md`](<@site/_dogfooding/_pages tests/linking/nested/page-b.md>)

website/_dogfooding/_pages tests/linking/page-a.md

@@ -0,0 +1,19 @@
+# Linking Test - Page A
+
+## Relative file path links
+
+- [`./index.md`](./index.md)
+- [`./page-a.md`](./page-a.md)
+- [`./nested/page-b.md`](./nested/page-b.md)
+
+## Absolute file path links
+
+- [`/index.md`](/linking/index.md)
+- [`/page-a.md`](/linking/page-a.md)
+- [`/nested/page-b.md`](/linking/nested/page-b.md)
+
+## Site alias file path links
+
+- [`@site/_dogfooding/_pages tests/linking/index.md`](<@site/_dogfooding/_pages tests/linking/index.md>)
+- [`@site/_dogfooding/_pages tests/linking/page-a.md`](<@site/_dogfooding/_pages tests/linking/page-a.md>)
+- [`@site/_dogfooding/_pages tests/linking/nested/page-b.md`](<@site/_dogfooding/_pages tests/linking/nested/page-b.md>)