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/__tests__/__fixtures__/website/docusaurus.config.js

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+module.exports = {
+  title: 'My Site',
+  tagline: 'The tagline of my site',
+  url: 'https://your-docusaurus-test-site.com',
+  baseUrl: '/',
+  favicon: 'img/favicon.ico',
+};

packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/index.md

@@ -0,0 +1,2 @@
+
+Markdown index page

packages/docusaurus-plugin-content-pages/src/__tests__/__fixtures__/website/src/pages/hello/mdxPage.mdx

@@ -0,0 +1,5 @@
+---
+title: mdx page
+description: my mdx page
+---
+MDX page

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

@@ -6,23 +6,15 @@
  */
 
 import path from 'path';
+import {loadContext} from '@docusaurus/core/lib/server';
 
 import pluginContentPages from '../index';
-import {LoadContext} from '@docusaurus/types';
 import normalizePluginOptions from './pluginOptionSchema.test';
 
 describe('docusaurus-plugin-content-pages', () => {
   test('simple pages', async () => {
     const siteDir = path.join(__dirname, '__fixtures__', 'website');
-    const siteConfig = {
-      title: 'Hello',
-      baseUrl: '/',
-      url: 'https://docusaurus.io',
-    };
-    const context = {
-      siteDir,
-      siteConfig,
-    } as LoadContext;
+    const context = loadContext(siteDir);
     const pluginPath = 'src/pages';
     const plugin = pluginContentPages(
       context,
@@ -34,14 +26,27 @@ describe('docusaurus-plugin-content-pages', () => {
 
     expect(pagesMetadatas).toEqual([
       {
+        type: 'jsx',
         permalink: '/',
         source: path.join('@site', pluginPath, 'index.js'),
       },
       {
+        type: 'jsx',
         permalink: '/typescript',
         source: path.join('@site', pluginPath, 'typescript.tsx'),
       },
       {
+        type: 'mdx',
+        permalink: '/hello/',
+        source: path.join('@site', pluginPath, 'hello', 'index.md'),
+      },
+      {
+        type: 'mdx',
+        permalink: '/hello/mdxPage',
+        source: path.join('@site', pluginPath, 'hello', 'mdxPage.mdx'),
+      },
+      {
+        type: 'jsx',
         permalink: '/hello/world',
         source: path.join('@site', pluginPath, 'hello', 'world.js'),
       },

packages/docusaurus-plugin-content-pages/src/__tests__/pluginOptionSchema.test.ts

@@ -6,8 +6,11 @@
  */
 
 import {PluginOptionSchema, DEFAULT_OPTIONS} from '../pluginOptionSchema';
+import {PluginOptions} from '../types';
 
-export default function normalizePluginOptions(options) {
+export default function normalizePluginOptions(
+  options: Partial<PluginOptions>,
+) {
   const {value, error} = PluginOptionSchema.validate(options, {
     convert: false,
   });
@@ -19,29 +22,30 @@ export default function normalizePluginOptions(options) {
 }
 
 describe('normalizePagesPluginOptions', () => {
-  test('should return default options for undefined user options', async () => {
-    const {value} = await PluginOptionSchema.validate({});
+  test('should return default options for undefined user options', () => {
+    const value = normalizePluginOptions({});
     expect(value).toEqual(DEFAULT_OPTIONS);
   });
 
-  test('should fill in default options for partially defined user options', async () => {
-    const {value} = await PluginOptionSchema.validate({path: 'src/pages'});
+  test('should fill in default options for partially defined user options', () => {
+    const value = normalizePluginOptions({path: 'src/pages'});
     expect(value).toEqual(DEFAULT_OPTIONS);
   });
 
-  test('should accept correctly defined user options', async () => {
+  test('should accept correctly defined user options', () => {
     const userOptions = {
       path: 'src/my-pages',
       routeBasePath: 'my-pages',
       include: ['**/*.{js,jsx,ts,tsx}'],
     };
-    const {value} = await PluginOptionSchema.validate(userOptions);
-    expect(value).toEqual(userOptions);
+    const value = normalizePluginOptions(userOptions);
+    expect(value).toEqual({...DEFAULT_OPTIONS, ...userOptions});
   });
 
   test('should reject bad path inputs', () => {
     expect(() => {
       normalizePluginOptions({
+        // @ts-expect-error: bad attribute
         path: 42,
       });
     }).toThrowErrorMatchingInlineSnapshot(`"\\"path\\" must be a string"`);