feat(v2): markdown pages (#3158)

* markdown pages POC

* add remark admonition, mdx provider, yarn2npm...

* pluginContentPages md/mdx tests

* pluginContentPages md/mdx tests

* add relative file path test link to showcase link problem

* fix Markdown pages issues after merge

* fix broken links found in markdown pages

* fix tests

* factorize common validation in @docusaurus/utils-validation

* add some documentation

* add using plugins doc

* minor md pages fixes

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

@@ -8,23 +8,46 @@
 import globby from 'globby';
 import fs from 'fs';
 import path from 'path';
-import {encodePath, fileToPath, aliasedSitePath} from '@docusaurus/utils';
+import {
+  encodePath,
+  fileToPath,
+  aliasedSitePath,
+  docuHash,
+} from '@docusaurus/utils';
 import {
   LoadContext,
   Plugin,
   OptionValidationContext,
   ValidationResult,
+  ConfigureWebpackUtils,
 } from '@docusaurus/types';
-
-import {PluginOptions, LoadedContent} from './types';
+import {Configuration, Loader} from 'webpack';
+import admonitions from 'remark-admonitions';
 import {PluginOptionSchema} from './pluginOptionSchema';
 import {ValidationError} from '@hapi/joi';
 
+import {PluginOptions, LoadedContent, Metadata} from './types';
+
+const isMarkdownSource = (source: string) =>
+  source.endsWith('.md') || source.endsWith('.mdx');
+
 export default function pluginContentPages(
   context: LoadContext,
   options: PluginOptions,
 ): Plugin<LoadedContent | null, typeof PluginOptionSchema> {
-  const contentPath = path.resolve(context.siteDir, options.path);
+  if (options.admonitions) {
+    options.remarkPlugins = options.remarkPlugins.concat([
+      [admonitions, options.admonitions || {}],
+    ]);
+  }
+  const {siteConfig, siteDir, generatedFilesDir} = context;
+
+  const contentPath = path.resolve(siteDir, options.path);
+
+  const dataDir = path.join(
+    generatedFilesDir,
+    'docusaurus-plugin-content-pages',
+  );
 
   return {
     name: 'docusaurus-plugin-content-pages',
@@ -35,9 +58,18 @@ export default function pluginContentPages(
       return [...globPattern];
     },
 
+    getClientModules() {
+      const modules = [];
+
+      if (options.admonitions) {
+        modules.push(require.resolve('remark-admonitions/styles/infima.css'));
+      }
+
+      return modules;
+    },
+
     async loadContent() {
       const {include} = options;
-      const {siteConfig, siteDir} = context;
       const pagesDir = contentPath;
 
       if (!fs.existsSync(pagesDir)) {
@@ -49,16 +81,27 @@ export default function pluginContentPages(
         cwd: pagesDir,
       });
 
-      return pagesFiles.map((relativeSource) => {
+      function toMetadata(relativeSource: string): Metadata {
         const source = path.join(pagesDir, relativeSource);
         const aliasedSource = aliasedSitePath(source, siteDir);
         const pathName = encodePath(fileToPath(relativeSource));
-        // Default Language.
-        return {
-          permalink: pathName.replace(/^\//, baseUrl || ''),
-          source: aliasedSource,
-        };
-      });
+        const permalink = pathName.replace(/^\//, baseUrl || '');
+        if (isMarkdownSource(relativeSource)) {
+          return {
+            type: 'mdx',
+            permalink,
+            source: aliasedSource,
+          };
+        } else {
+          return {
+            type: 'jsx',
+            permalink,
+            source: aliasedSource,
+          };
+        }
+      }
+
+      return pagesFiles.map(toMetadata);
     },
 
     async contentLoaded({content, actions}) {
@@ -66,22 +109,89 @@ export default function pluginContentPages(
         return;
       }
 
-      const {addRoute} = actions;
+      const {addRoute, createData} = actions;
 
       await Promise.all(
-        content.map(async (metadataItem) => {
-          const {permalink, source} = metadataItem;
-          addRoute({
-            path: permalink,
-            component: source,
-            exact: true,
-            modules: {
-              config: `@generated/docusaurus.config`,
-            },
-          });
+        content.map(async (metadata) => {
+          const {permalink, source} = metadata;
+          if (metadata.type === 'mdx') {
+            await createData(
+              // Note that this created data path must be in sync with
+              // metadataPath provided to mdx-loader.
+              `${docuHash(metadata.source)}.json`,
+              JSON.stringify(metadata, null, 2),
+            );
+            addRoute({
+              path: permalink,
+              component: options.mdxPageComponent,
+              exact: true,
+              modules: {
+                content: source,
+              },
+            });
+          } else {
+            addRoute({
+              path: permalink,
+              component: source,
+              exact: true,
+              modules: {
+                config: `@generated/docusaurus.config`,
+              },
+            });
+          }
         }),
       );
     },
+
+    configureWebpack(
+      _config: Configuration,
+      isServer: boolean,
+      {getBabelLoader, getCacheLoader}: ConfigureWebpackUtils,
+    ) {
+      const {rehypePlugins, remarkPlugins} = options;
+      return {
+        resolve: {
+          alias: {
+            '~pages': dataDir,
+          },
+        },
+        module: {
+          rules: [
+            {
+              test: /(\.mdx?)$/,
+              include: [contentPath],
+              use: [
+                getCacheLoader(isServer),
+                getBabelLoader(isServer),
+                {
+                  loader: require.resolve('@docusaurus/mdx-loader'),
+                  options: {
+                    remarkPlugins,
+                    rehypePlugins,
+                    // Note that metadataPath must be the same/in-sync as
+                    // the path from createData for each MDX.
+                    metadataPath: (mdxPath: string) => {
+                      const aliasedSource = aliasedSitePath(mdxPath, siteDir);
+                      return path.join(
+                        dataDir,
+                        `${docuHash(aliasedSource)}.json`,
+                      );
+                    },
+                  },
+                },
+                {
+                  loader: path.resolve(__dirname, './markdownLoader.js'),
+                  options: {
+                    // siteDir,
+                    // contentPath,
+                  },
+                },
+              ].filter(Boolean) as Loader[],
+            },
+          ],
+        },
+      };
+    },
   };
 }