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-utils-validation/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@docusaurus/utils-validation",
+  "version": "2.0.0-alpha.60",
+  "description": "Node validation utility functions for Docusaurus packages",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/hapi__joi": "^17.1.2"
+  },
+  "dependencies": {
+    "@hapi/joi": "17.1.1"
+  },
+  "engines": {
+    "node": ">=10.15.1"
+  }
+}

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

@@ -0,0 +1,45 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`validation schemas AdmonitionsSchema 1`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas AdmonitionsSchema 2`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas AdmonitionsSchema 3`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas AdmonitionsSchema 4`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas RehypePluginsSchema 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RehypePluginsSchema 2`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RehypePluginsSchema 3`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RehypePluginsSchema 4`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema 5`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema 6`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema 7`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema 8`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema 9`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RemarkPluginsSchema 2`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RemarkPluginsSchema 3`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RemarkPluginsSchema 4`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema 5`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema 6`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema 7`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema 8`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema 9`] = `"\\"[0]\\" does not match any of the allowed types"`;

packages/docusaurus-utils-validation/src/__tests__/index.test.ts

@@ -0,0 +1,84 @@
+/**
+ * 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 * as Joi from '@hapi/joi';
+
+import {
+  AdmonitionsSchema,
+  RehypePluginsSchema,
+  RemarkPluginsSchema,
+} from '../index';
+
+function createTestHelpers({
+  schema,
+  defaultValue,
+}: {
+  schema: Joi.SchemaLike;
+  defaultValue?: unknown;
+}) {
+  function testOK(value: unknown) {
+    expect(Joi.attempt(value, schema)).toEqual(value ?? defaultValue);
+  }
+
+  function testFail(value: unknown) {
+    expect(() => Joi.attempt(value, schema)).toThrowErrorMatchingSnapshot();
+  }
+
+  return {testOK, testFail};
+}
+
+function testMarkdownPluginSchemas(schema: Joi.SchemaLike) {
+  const {testOK, testFail} = createTestHelpers({
+    schema,
+    defaultValue: [],
+  });
+
+  testOK(undefined);
+  testOK([function () {}]);
+  testOK([[function () {}, {attr: 'val'}]]);
+  testOK([
+    [function () {}, {attr: 'val'}],
+    function () {},
+    [function () {}, {attr: 'val'}],
+  ]);
+
+  testFail(null);
+  testFail(false);
+  testFail(3);
+  testFail([null]);
+  testFail([false]);
+  testFail([3]);
+  testFail([[]]);
+  testFail([[function () {}, undefined]]);
+  testFail([[function () {}, true]]);
+}
+
+describe('validation schemas', () => {
+  test('AdmonitionsSchema', () => {
+    const {testOK, testFail} = createTestHelpers({
+      schema: AdmonitionsSchema,
+      defaultValue: {},
+    });
+
+    testOK(undefined);
+    testOK({});
+    testOK({attr: 'val'});
+
+    testFail(null);
+    testFail(3);
+    testFail(true);
+    testFail([]);
+  });
+
+  test('RemarkPluginsSchema', () => {
+    testMarkdownPluginSchemas(RemarkPluginsSchema);
+  });
+
+  test('RehypePluginsSchema', () => {
+    testMarkdownPluginSchemas(RehypePluginsSchema);
+  });
+});

packages/docusaurus-utils-validation/src/index.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 * as Joi from '@hapi/joi';
+
+const MarkdownPluginsSchema = Joi.array()
+  .items(
+    Joi.array()
+      // TODO, this allows [config,fn] too?
+      .items(Joi.function().required(), Joi.object().required())
+      .length(2),
+    Joi.function(),
+  )
+  .default([]);
+
+export const RemarkPluginsSchema = MarkdownPluginsSchema;
+export const RehypePluginsSchema = MarkdownPluginsSchema;
+
+export const AdmonitionsSchema = Joi.object().default({});

packages/docusaurus-utils-validation/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "incremental": true,
+    "tsBuildInfoFile": "./lib/.tsbuildinfo",
+    "rootDir": "src",
+    "outDir": "lib"
+  }
+}