feat(v2): add option validation for remaining official plugins (#2970)

* feat(v2): add option validation lifecycle method

* chore(v2): add dependencies

* chore(v2): add yup dependency

* feat(v2): add option validation for plugin-content-docs

* chore(v2): add facebook copyright

* refactor(v2): remove unused variable

* chore(v2): add dependencies

* chore(v2): add copyright

* fix(v2): use strict for option validation

* feat(v2): add option validation for plugin-content-pages

* feat(v2): add schema for plugin-google-analytics and plugin-google-gtag

* feat(v2): add option validation for plugin-sitemap

* chore(v2): add dependency for yup

* fix(v2): remove strict to allow normalization

* refactor(v2): refactor validate method

* feat(v2): modify existing tests

* feat(v2): add tests for plugin normalization

* style(v2): use a more descriptive filename for schema

* feat(v2): add normalization tests

* feat(v2): add more tests for option validation

* refactor(v2): remove unused code

* refactor(v2): remove unused code

* refactor(v2): refactor methods and types

* feat(v2): replace Yup with Joi

* fix(v2): fix plugin-content-docs schema

* feat(v2): modify tests for plugin-content-docs

* fix(v2): fix a typo

* refactor(v2): improve tests and refactor code

* feat(v2): support both commonjs and ES modules

* refactor(v2): refactor validateOption method

* style(v2): fix eslint errors and typo in types

* chore(v2): remove unused yup dependency

* style(v2): standardize naming across official plugins

* chore(v2): update test snapshots

* chore(v2): remove obsolete snapshots

* chore(v2): fix a typo and check test

* feat(v2): add validation for new field

* feat(v2): add test for new field

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

@@ -12,6 +12,7 @@ import commander from 'commander';
 import fs from 'fs-extra';
 import pluginContentDocs from '../index';
 import loadEnv from '../env';
+import normalizePluginOptions from './pluginOptionSchema.test';
 import {loadContext} from '@docusaurus/core/src/server/index';
 import {applyConfigureWebpack} from '@docusaurus/core/src/webpack/utils';
 import {RouteConfig} from '@docusaurus/types';
@@ -42,9 +43,12 @@ test('site with wrong sidebar file', async () => {
   const siteDir = path.join(__dirname, '__fixtures__', 'simple-site');
   const context = loadContext(siteDir);
   const sidebarPath = path.join(siteDir, 'wrong-sidebars.json');
-  const plugin = pluginContentDocs(context, {
-    sidebarPath,
-  });
+  const plugin = pluginContentDocs(
+    context,
+    normalizePluginOptions({
+      sidebarPath,
+    }),
+  );
   await expect(plugin.loadContent()).rejects.toThrowErrorMatchingSnapshot();
 });
 
@@ -54,7 +58,7 @@ describe('empty/no docs website', () => {
 
   test('no files in docs folder', async () => {
     await fs.ensureDir(path.join(siteDir, 'docs'));
-    const plugin = pluginContentDocs(context, {});
+    const plugin = pluginContentDocs(context, normalizePluginOptions({}));
     const content = await plugin.loadContent();
     const {docsMetadata, docsSidebars} = content;
     expect(docsMetadata).toMatchInlineSnapshot(`Object {}`);
@@ -73,7 +77,12 @@ describe('empty/no docs website', () => {
   });
 
   test('docs folder does not exist', async () => {
-    const plugin = pluginContentDocs(context, {path: '/path/does/not/exist/'});
+    const plugin = pluginContentDocs(
+      context,
+      normalizePluginOptions({
+        path: '/path/does/not/exist/',
+      }),
+    );
     const content = await plugin.loadContent();
     expect(content).toBeNull();
   });
@@ -84,11 +93,14 @@ describe('simple website', () => {
   const context = loadContext(siteDir);
   const sidebarPath = path.join(siteDir, 'sidebars.json');
   const pluginPath = 'docs';
-  const plugin = pluginContentDocs(context, {
-    path: pluginPath,
-    sidebarPath,
-    homePageId: 'hello',
-  });
+  const plugin = pluginContentDocs(
+    context,
+    normalizePluginOptions({
+      path: pluginPath,
+      sidebarPath,
+      homePageId: 'hello',
+    }),
+  );
   const pluginContentDir = path.join(context.generatedFilesDir, plugin.name);
 
   test('extendCli - docsVersion', () => {
@@ -215,11 +227,14 @@ describe('versioned website', () => {
   const context = loadContext(siteDir);
   const sidebarPath = path.join(siteDir, 'sidebars.json');
   const routeBasePath = 'docs';
-  const plugin = pluginContentDocs(context, {
-    routeBasePath,
-    sidebarPath,
-    homePageId: 'hello',
-  });
+  const plugin = pluginContentDocs(
+    context,
+    normalizePluginOptions({
+      routeBasePath,
+      sidebarPath,
+      homePageId: 'hello',
+    }),
+  );
   const env = loadEnv(siteDir);
   const {docsDir: versionedDir} = env.versioning;
   const pluginContentDir = path.join(context.generatedFilesDir, plugin.name);

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

@@ -0,0 +1,83 @@
+/**
+ * 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 {PluginOptionSchema, DEFAULT_OPTIONS} from '../pluginOptionSchema';
+
+export default function normalizePluginOptions(options) {
+  const {value, error} = PluginOptionSchema.validate(options, {
+    convert: false,
+  });
+  if (error) {
+    throw error;
+  } else {
+    return value;
+  }
+}
+
+describe('normalizeDocsPluginOptions', () => {
+  test('should return default options for undefined user options', async () => {
+    const {value} = await PluginOptionSchema.validate({});
+    expect(value).toEqual(DEFAULT_OPTIONS);
+  });
+
+  test('should accept correctly defined user options', async () => {
+    const userOptions = {
+      path: 'my-docs', // Path to data on filesystem, relative to site dir.
+      routeBasePath: 'my-docs', // URL Route.
+      homePageId: 'home', // Document id for docs home page.
+      include: ['**/*.{md,mdx}'], // Extensions to include.
+      sidebarPath: 'my-sidebar', // Path to sidebar configuration for showing a list of markdown pages.
+      docLayoutComponent: '@theme/DocPage',
+      docItemComponent: '@theme/DocItem',
+      remarkPlugins: [],
+      rehypePlugins: [],
+      showLastUpdateTime: true,
+      showLastUpdateAuthor: true,
+      admonitions: {},
+      excludeNextVersionDocs: true,
+    };
+
+    const {value} = await PluginOptionSchema.validate(userOptions);
+    expect(value).toEqual(userOptions);
+  });
+
+  test('should reject bad path inputs', () => {
+    expect(() => {
+      normalizePluginOptions({
+        path: 2,
+      });
+    }).toThrowErrorMatchingInlineSnapshot(`"\\"path\\" must be a string"`);
+  });
+
+  test('should reject bad include inputs', () => {
+    expect(() => {
+      normalizePluginOptions({
+        include: '**/*.{md,mdx}',
+      });
+    }).toThrowErrorMatchingInlineSnapshot(`"\\"include\\" must be an array"`);
+  });
+
+  test('should reject bad showLastUpdateTime inputs', () => {
+    expect(() => {
+      normalizePluginOptions({
+        showLastUpdateTime: 'true',
+      });
+    }).toThrowErrorMatchingInlineSnapshot(
+      `"\\"showLastUpdateTime\\" must be a boolean"`,
+    );
+  });
+
+  test('should reject bad remarkPlugins input', () => {
+    expect(() => {
+      normalizePluginOptions({
+        remarkPlugins: 'remark-math',
+      });
+    }).toThrowErrorMatchingInlineSnapshot(
+      `"\\"remarkPlugins\\" must be an array"`,
+    );
+  });
+});

packages/docusaurus-plugin-content-docs/src/__tests__/sidebars.test.ts

@@ -24,7 +24,7 @@ describe('loadSidebars', () => {
     expect(result).toMatchSnapshot();
   });
 
-  test('sidebars shortand and longform lead to exact same sidebar', async () => {
+  test('sidebars shorthand and longform lead to exact same sidebar', async () => {
     const sidebarPath1 = path.join(fixtureDir, 'sidebars-category.js');
     const sidebarPath2 = path.join(
       fixtureDir,