feat(v2): blog + docs multi-instance plugins (#3204)

* stable createData namespacing + second-blog dogfooding

* Docs: support multi-instance + make community docs a separate instance

* tests: add 2nd docs instance to versioned site

* fix docs version cli tests

* fix docs versioning cli

* typo

* team: add link to my site

* better extendCli integration

* fix metadata tests

* tests for versioned site with second docs instance

* move some validation code to utils-validation

* fix missing dependency

* fix bad compiled output due to importing constants in ./client folder

* make docs tests easier to maintain

* refactors

* prevent lodash imports in client bundle

* redirect old community docs to new urls

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

@@ -1,45 +0,0 @@
-// 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__/__snapshots__/validationSchemas.test.ts.snap

@@ -0,0 +1,61 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`validation schemas AdmonitionsSchema: for value=[] 1`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas AdmonitionsSchema: for value=3 1`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas AdmonitionsSchema: for value=null 1`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas AdmonitionsSchema: for value=true 1`] = `"\\"value\\" must be of type object"`;
+
+exports[`validation schemas PluginIdSchema: for value="/docs" 1`] = `"\\"value\\" with value \\"/docs\\" fails to match the required pattern: /^[a-zA-Z_\\\\-]+$/"`;
+
+exports[`validation schemas PluginIdSchema: for value="do cs" 1`] = `"\\"value\\" with value \\"do cs\\" fails to match the required pattern: /^[a-zA-Z_\\\\-]+$/"`;
+
+exports[`validation schemas PluginIdSchema: for value="do/cs" 1`] = `"\\"value\\" with value \\"do/cs\\" fails to match the required pattern: /^[a-zA-Z_\\\\-]+$/"`;
+
+exports[`validation schemas PluginIdSchema: for value="docs/" 1`] = `"\\"value\\" with value \\"docs/\\" fails to match the required pattern: /^[a-zA-Z_\\\\-]+$/"`;
+
+exports[`validation schemas PluginIdSchema: for value=[] 1`] = `"\\"value\\" must be a string"`;
+
+exports[`validation schemas PluginIdSchema: for value=3 1`] = `"\\"value\\" must be a string"`;
+
+exports[`validation schemas PluginIdSchema: for value=null 1`] = `"\\"value\\" must be a string"`;
+
+exports[`validation schemas PluginIdSchema: for value=true 1`] = `"\\"value\\" must be a string"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=[[]] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=[[null,null]] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=[[null,true]] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=[3] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=[false] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=[null] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=3 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=false 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RehypePluginsSchema: for value=null 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=[[]] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=[[null,null]] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=[[null,true]] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=[3] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=[false] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=[null] 1`] = `"\\"[0]\\" does not match any of the allowed types"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=3 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=false 1`] = `"\\"value\\" must be an array"`;
+
+exports[`validation schemas RemarkPluginsSchema: for value=null 1`] = `"\\"value\\" must be an array"`;

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

@@ -11,7 +11,8 @@ import {
   AdmonitionsSchema,
   RehypePluginsSchema,
   RemarkPluginsSchema,
-} from '../index';
+  PluginIdSchema,
+} from '../validationSchemas';
 
 function createTestHelpers({
   schema,
@@ -25,7 +26,10 @@ function createTestHelpers({
   }
 
   function testFail(value: unknown) {
-    expect(() => Joi.attempt(value, schema)).toThrowErrorMatchingSnapshot();
+    expect(() => Joi.attempt(value, schema)).toThrowErrorMatchingSnapshot(
+      // @ts-expect-error: seems ok at runtime, but bad typedef
+      `for value=${JSON.stringify(value)}`,
+    );
   }
 
   return {testOK, testFail};
@@ -58,6 +62,27 @@ function testMarkdownPluginSchemas(schema: Joi.SchemaLike) {
 }
 
 describe('validation schemas', () => {
+  test('PluginIdSchema', () => {
+    const {testOK, testFail} = createTestHelpers({
+      schema: PluginIdSchema,
+      defaultValue: 'default',
+    });
+
+    testOK(undefined);
+    testOK('docs');
+    testOK('default');
+    testOK('plugin-id_with-simple-special-chars');
+
+    testFail('/docs');
+    testFail('docs/');
+    testFail('do/cs');
+    testFail('do cs');
+    testFail(null);
+    testFail(3);
+    testFail(true);
+    testFail([]);
+  });
+
   test('AdmonitionsSchema', () => {
     const {testOK, testFail} = createTestHelpers({
       schema: AdmonitionsSchema,

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

@@ -4,19 +4,6 @@
  * 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({});
+export * from './validationUtils';
+export * from './validationSchemas';

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

@@ -0,0 +1,27 @@
+/**
+ * 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';
+
+export const PluginIdSchema = Joi.string()
+  .regex(/^[a-zA-Z_\-]+$/)
+  // duplicate core constant, otherwise cyclic dependency is created :(
+  .default('default');
+
+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/src/validationUtils.ts

@@ -0,0 +1,85 @@
+/**
+ * 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 chalk from 'chalk';
+import {PluginIdSchema} from './validationSchemas';
+
+// TODO temporary escape hatch for alpha-60: to be removed soon
+// Our validation schemas might be buggy at first
+// will permit users to bypass validation until we fix all validation errors
+// see for example: https://github.com/facebook/docusaurus/pull/3120
+// Undocumented on purpose, as we don't want users to keep using it over time
+// Maybe we'll make this escape hatch official some day, with a better api?
+export const isValidationDisabledEscapeHatch =
+  process.env.DISABLE_DOCUSAURUS_VALIDATION === 'true';
+
+if (isValidationDisabledEscapeHatch) {
+  console.error(
+    chalk.red(
+      'You should avoid using DISABLE_DOCUSAURUS_VALIDATION escape hatch, this will be removed',
+    ),
+  );
+}
+
+export const logValidationBugReportHint = () => {
+  console.log(
+    `\n${chalk.red('A validation error occured.')}${chalk.cyanBright(
+      '\nThe validation system was added recently to Docusaurus as an attempt to avoid user configuration errors.' +
+        '\nWe may have made some mistakes.' +
+        '\nIf you think your configuration is valid and should keep working, please open a bug report.',
+    )}\n`,
+  );
+};
+
+export function normalizePluginOptions<T extends {id?: string}>(
+  schema: Joi.ObjectSchema<T>,
+  options: unknown,
+) {
+  // All plugins can be provided an "id" option (multi-instance support)
+  // we add schema validation automatically
+  const finalSchema = schema.append({
+    id: PluginIdSchema,
+  });
+  const {error, value} = finalSchema.validate(options, {
+    convert: false,
+  });
+  if (error) {
+    logValidationBugReportHint();
+    if (isValidationDisabledEscapeHatch) {
+      console.error(error);
+      return options;
+    } else {
+      throw error;
+    }
+  }
+  return value;
+}
+
+export function normalizeThemeConfig<T>(
+  schema: Joi.ObjectSchema<T>,
+  themeConfig: unknown,
+) {
+  // A theme should only validate his "slice" of the full themeConfig,
+  // not the whole object, so we allow unknown attributes
+  // otherwise one theme would fail validating the data of another theme
+  const finalSchema = schema.unknown();
+
+  const {error, value} = finalSchema.validate(themeConfig, {
+    convert: false,
+  });
+
+  if (error) {
+    logValidationBugReportHint();
+    if (isValidationDisabledEscapeHatch) {
+      console.error(error);
+      return themeConfig;
+    } else {
+      throw error;
+    }
+  }
+  return value;
+}