@docusaurus/plugin-client-redirects 2.0.0-beta.2 → 2.0.0-beta.22

package/src/collectRedirects.ts

@@ -5,59 +5,68 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {flatten, uniqBy, difference, groupBy} from 'lodash';
-import {
-  PluginContext,
-  RedirectMetadata,
-  PluginOptions,
-  RedirectOption,
-} from './types';
+import _ from 'lodash';
+import logger from '@docusaurus/logger';
+import {applyTrailingSlash} from '@docusaurus/utils-common';
 import {
   createFromExtensionsRedirects,
   createToExtensionsRedirects,
 } from './extensionRedirects';
 import {validateRedirect} from './redirectValidation';
-import {applyTrailingSlash} from '@docusaurus/utils-common';
-
-import chalk from 'chalk';
+import type {PluginOptions, RedirectOption} from './options';
+import type {PluginContext, RedirectItem} from './types';
 
 export default function collectRedirects(
   pluginContext: PluginContext,
   trailingSlash: boolean | undefined,
-): RedirectMetadata[] {
-  let redirects = doCollectRedirects(pluginContext);
-  redirects = applyRedirectsTrailingSlash(redirects, trailingSlash);
+): RedirectItem[] {
+  // For each plugin config option, create the appropriate redirects
+  const redirects = [
+    ...createFromExtensionsRedirects(
+      pluginContext.relativeRoutesPaths,
+      pluginContext.options.fromExtensions,
+    ),
+    ...createToExtensionsRedirects(
+      pluginContext.relativeRoutesPaths,
+      pluginContext.options.toExtensions,
+    ),
+    ...createRedirectsOptionRedirects(pluginContext.options.redirects),
+    ...createCreateRedirectsOptionRedirects(
+      pluginContext.relativeRoutesPaths,
+      pluginContext.options.createRedirects,
+    ),
+  ].map((redirect) => ({
+    ...redirect,
+    // Given a redirect with `to: "/abc"` and `trailingSlash` enabled:
+    //
+    // - We don't want to reject `to: "/abc"`, as that unambiguously points to
+    // `/abc/` now;
+    // - We want to redirect `to: /abc/` without the user having to change all
+    // her redirect plugin options
+    //
+    // It should be easy to toggle `trailingSlash` option without having to
+    // change other configs
+    to: applyTrailingSlash(redirect.to, {
+      trailingSlash,
+      baseUrl: pluginContext.baseUrl,
+    }),
+  }));
+
   validateCollectedRedirects(redirects, pluginContext);
   return filterUnwantedRedirects(redirects, pluginContext);
 }
 
-// If users wants to redirect to=/abc and they enable trailingSlash=true then
-// => we don't want to reject the to=/abc (as only /abc/ is an existing/valid path now)
-// => we want to redirect to=/abc/ without the user having to change all its redirect plugin options
-// It should be easy to toggle siteConfig.trailingSlash option without having to change other configs
-function applyRedirectsTrailingSlash(
-  redirects: RedirectMetadata[],
-  trailingSlash: boolean | undefined,
-) {
-  return redirects.map((redirect) => {
-    return {
-      ...redirect,
-      to: applyTrailingSlash(redirect.to, trailingSlash),
-    };
-  });
-}
-
 function validateCollectedRedirects(
-  redirects: RedirectMetadata[],
+  redirects: RedirectItem[],
   pluginContext: PluginContext,
 ) {
-  const redirectValidationErrors: string[] = redirects
+  const redirectValidationErrors = redirects
     .map((redirect) => {
       try {
         validateRedirect(redirect);
         return undefined;
-      } catch (e) {
-        return e.message;
+      } catch (err) {
+        return (err as Error).message;
       }
     })
     .filter(Boolean);
@@ -71,7 +80,7 @@ function validateCollectedRedirects(
 
   const allowedToPaths = pluginContext.relativeRoutesPaths;
   const toPaths = redirects.map((redirect) => redirect.to);
-  const illegalToPaths = difference(toPaths, allowedToPaths);
+  const illegalToPaths = _.difference(toPaths, allowedToPaths);
   if (illegalToPaths.length > 0) {
     throw new Error(
       `You are trying to create client-side redirections to paths that do not exist:
@@ -85,101 +94,66 @@ Valid paths you can redirect to:
 }
 
 function filterUnwantedRedirects(
-  redirects: RedirectMetadata[],
+  redirects: RedirectItem[],
   pluginContext: PluginContext,
-): RedirectMetadata[] {
-  // we don't want to create twice the same redirect
-  // that would lead to writing twice the same html redirection file
-  Object.entries(groupBy(redirects, (redirect) => redirect.from)).forEach(
+): RedirectItem[] {
+  // We don't want to create the same redirect twice, since that would lead to
+  // writing the same html redirection file twice.
+  Object.entries(_.groupBy(redirects, (redirect) => redirect.from)).forEach(
     ([from, groupedFromRedirects]) => {
       if (groupedFromRedirects.length > 1) {
-        console.error(
-          chalk.red(
-            `@docusaurus/plugin-client-redirects: multiple redirects are created with the same "from" pathname=${from}
-It is not possible to redirect the same pathname to multiple destinations:
-- ${groupedFromRedirects.map((r) => JSON.stringify(r)).join('\n- ')}
-`,
-          ),
-        );
+        logger.report(
+          pluginContext.siteConfig.onDuplicateRoutes,
+        )`name=${'@docusaurus/plugin-client-redirects'}: multiple redirects are created with the same "from" pathname: path=${from}
+It is not possible to redirect the same pathname to multiple destinations:${groupedFromRedirects.map(
+          (r) => JSON.stringify(r),
+        )}`;
       }
     },
   );
-  const collectedRedirects = uniqBy(redirects, (redirect) => redirect.from);
+  const collectedRedirects = _.uniqBy(redirects, (redirect) => redirect.from);
 
-  // We don't want to override an already existing route with a redirect file!
-  const redirectsOverridingExistingPath = collectedRedirects.filter(
-    (redirect) => pluginContext.relativeRoutesPaths.includes(redirect.from),
-  );
-  if (redirectsOverridingExistingPath.length > 0) {
-    console.error(
-      chalk.red(
-        `@docusaurus/plugin-client-redirects: some redirects would override existing paths, and will be ignored:
-- ${redirectsOverridingExistingPath.map((r) => JSON.stringify(r)).join('\n- ')}
-`,
-      ),
+  const {false: newRedirects = [], true: redirectsOverridingExistingPath = []} =
+    _.groupBy(collectedRedirects, (redirect) =>
+      pluginContext.relativeRoutesPaths.includes(redirect.from),
     );
+  if (redirectsOverridingExistingPath.length > 0) {
+    logger.report(
+      pluginContext.siteConfig.onDuplicateRoutes,
+    )`name=${'@docusaurus/plugin-client-redirects'}: some redirects would override existing paths, and will be ignored:${redirectsOverridingExistingPath.map(
+      (r) => JSON.stringify(r),
+    )}`;
   }
-  return collectedRedirects.filter(
-    (redirect) => !pluginContext.relativeRoutesPaths.includes(redirect.from),
-  );
-}
-
-// For each plugin config option, create the appropriate redirects
-function doCollectRedirects(pluginContext: PluginContext): RedirectMetadata[] {
-  return [
-    ...createFromExtensionsRedirects(
-      pluginContext.relativeRoutesPaths,
-      pluginContext.options.fromExtensions,
-    ),
-    ...createToExtensionsRedirects(
-      pluginContext.relativeRoutesPaths,
-      pluginContext.options.toExtensions,
-    ),
-    ...createRedirectsOptionRedirects(pluginContext.options.redirects),
-    ...createCreateRedirectsOptionRedirects(
-      pluginContext.relativeRoutesPaths,
-      pluginContext.options.createRedirects,
-    ),
-  ];
+  return newRedirects;
 }
 
 function createRedirectsOptionRedirects(
   redirectsOption: PluginOptions['redirects'],
-): RedirectMetadata[] {
-  // For conveniency, user can use a string or a string[]
-  function optionToRedirects(option: RedirectOption): RedirectMetadata[] {
+): RedirectItem[] {
+  // For convenience, user can use a string or a string[]
+  function optionToRedirects(option: RedirectOption): RedirectItem[] {
     if (typeof option.from === 'string') {
       return [{from: option.from, to: option.to}];
     }
-    return option.from.map((from) => ({
-      from,
-      to: option.to,
-    }));
+    return option.from.map((from) => ({from, to: option.to}));
   }
 
-  return flatten(redirectsOption.map(optionToRedirects));
+  return redirectsOption.flatMap(optionToRedirects);
 }
 
 // Create redirects from the "createRedirects" fn provided by the user
 function createCreateRedirectsOptionRedirects(
   paths: string[],
   createRedirects: PluginOptions['createRedirects'],
-): RedirectMetadata[] {
-  function createPathRedirects(path: string): RedirectMetadata[] {
-    const fromsMixed: string | string[] = createRedirects
-      ? createRedirects(path) || []
-      : [];
+): RedirectItem[] {
+  function createPathRedirects(path: string): RedirectItem[] {
+    const fromsMixed: string | string[] = createRedirects?.(path) ?? [];
 
     const froms: string[] =
       typeof fromsMixed === 'string' ? [fromsMixed] : fromsMixed;
 
-    return froms.map((from) => {
-      return {
-        from,
-        to: path,
-      };
-    });
+    return froms.map((from) => ({from, to: path}));
   }
 
-  return flatten(paths.map(createPathRedirects));
+  return paths.flatMap(createPathRedirects);
 }

package/src/createRedirectPageContent.ts

@@ -5,26 +5,24 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import _ from 'lodash';
 import * as eta from 'eta';
 import redirectPageTemplate from './templates/redirectPage.template.html';
-import {memoize} from 'lodash';
 
-type CreateRedirectPageOptions = {
-  toUrl: string;
-};
-
-const getCompiledRedirectPageTemplate = memoize(() => {
-  return eta.compile(redirectPageTemplate.trim());
-});
+const getCompiledRedirectPageTemplate = _.memoize(() =>
+  eta.compile(redirectPageTemplate.trim()),
+);
 
-function renderRedirectPageTemplate(data: Record<string, unknown>) {
+function renderRedirectPageTemplate(data: {toUrl: string}) {
   const compiled = getCompiledRedirectPageTemplate();
   return compiled(data, eta.defaultConfig);
 }
 
 export default function createRedirectPageContent({
   toUrl,
-}: CreateRedirectPageOptions): string {
+}: {
+  toUrl: string;
+}): string {
   return renderRedirectPageTemplate({
     toUrl: encodeURI(toUrl),
   });

package/src/deps.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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.
+ */
+
+// TODO incompatible declaration file
+declare module 'eta' {
+  export const defaultConfig: object;
+
+  export function compile(
+    template: string,
+    options?: object,
+  ): (data: object, config: object) => string;
+}

package/src/extensionRedirects.ts

@@ -5,12 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {flatten} from 'lodash';
-import {removeSuffix} from '@docusaurus/utils';
-import {RedirectMetadata} from './types';
+import {
+  addTrailingSlash,
+  removeSuffix,
+  removeTrailingSlash,
+} from '@docusaurus/utils';
+import type {RedirectItem} from './types';
 
 const ExtensionAdditionalMessage =
-  'If the redirect extension system is not good enough for your usecase, you can create redirects yourself with the "createRedirects" plugin option.';
+  'If the redirect extension system is not good enough for your use case, you can create redirects yourself with the "createRedirects" plugin option.';
 
 const validateExtension = (ext: string) => {
   if (!ext) {
@@ -37,35 +40,37 @@ const validateExtension = (ext: string) => {
 
 const addLeadingDot = (extension: string) => `.${extension}`;
 
-// Create new /path that redirects to existing an /path.html
+/**
+ * Create new `/path` that redirects to existing an `/path.html`
+ */
 export function createToExtensionsRedirects(
   paths: string[],
   extensions: string[],
-): RedirectMetadata[] {
+): RedirectItem[] {
   extensions.forEach(validateExtension);
 
   const dottedExtensions = extensions.map(addLeadingDot);
 
-  const createPathRedirects = (path: string): RedirectMetadata[] => {
+  const createPathRedirects = (path: string): RedirectItem[] => {
     const extensionFound = dottedExtensions.find((ext) => path.endsWith(ext));
     if (extensionFound) {
-      const routePathWithoutExtension = removeSuffix(path, extensionFound);
-      return [routePathWithoutExtension].map((from) => ({
-        from,
-        to: path,
-      }));
+      return [{from: removeSuffix(path, extensionFound), to: path}];
     }
     return [];
   };
 
-  return flatten(paths.map(createPathRedirects));
+  return paths.flatMap(createPathRedirects);
 }
 
-// Create new /path.html that redirects to existing an /path
+/**
+ * Create new `/path.html/index.html` that redirects to existing an `/path`
+ * The filename pattern might look weird but it's on purpose (see
+ * https://github.com/facebook/docusaurus/issues/5055)
+ */
 export function createFromExtensionsRedirects(
   paths: string[],
   extensions: string[],
-): RedirectMetadata[] {
+): RedirectItem[] {
   extensions.forEach(validateExtension);
 
   const dottedExtensions = extensions.map(addLeadingDot);
@@ -73,15 +78,19 @@ export function createFromExtensionsRedirects(
   const alreadyEndsWithAnExtension = (str: string) =>
     dottedExtensions.some((ext) => str.endsWith(ext));
 
-  const createPathRedirects = (path: string): RedirectMetadata[] => {
-    if (path === '' || path.endsWith('/') || alreadyEndsWithAnExtension(path)) {
+  const createPathRedirects = (path: string): RedirectItem[] => {
+    if (path === '' || path === '/' || alreadyEndsWithAnExtension(path)) {
       return [];
     }
     return extensions.map((ext) => ({
-      from: `${path}.${ext}`,
+      // /path => /path.html
+      // /path/ => /path.html/
+      from: path.endsWith('/')
+        ? addTrailingSlash(`${removeTrailingSlash(path)}.${ext}`)
+        : `${path}.${ext}`,
       to: path,
     }));
   };
 
-  return flatten(paths.map(createPathRedirects));
+  return paths.flatMap(createPathRedirects);
 }

package/src/index.ts

@@ -5,41 +5,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {LoadContext, Plugin, Props} from '@docusaurus/types';
-import {UserPluginOptions, PluginContext, RedirectMetadata} from './types';
-
-import normalizePluginOptions from './normalizePluginOptions';
+import {removePrefix, addLeadingSlash} from '@docusaurus/utils';
 import collectRedirects from './collectRedirects';
 import writeRedirectFiles, {
-  toRedirectFilesMetadata,
-  RedirectFileMetadata,
+  toRedirectFiles,
+  type RedirectFile,
 } from './writeRedirectFiles';
-import {removePrefix, addLeadingSlash} from '@docusaurus/utils';
-import chalk from 'chalk';
+import type {LoadContext, Plugin} from '@docusaurus/types';
+import type {PluginContext, RedirectItem} from './types';
+import type {PluginOptions, Options} from './options';
 
 export default function pluginClientRedirectsPages(
   context: LoadContext,
-  opts: UserPluginOptions,
-): Plugin<unknown> {
+  options: PluginOptions,
+): Plugin<void> {
   const {trailingSlash} = context.siteConfig;
 
-  const options = normalizePluginOptions(opts);
-
-  // Special case, when using trailingSlash=false we output /xyz.html files instead of /xyz/index.html
-  // It makes no sense to use option fromExtensions=["html"]: the redirect files would be the same as the original files
-  if (options.fromExtensions.includes('html') && trailingSlash === false) {
-    console.warn(
-      chalk.yellow(`Using the Docusaurus redirect plugin with fromExtensions=['html'] and siteConfig.trailingSlash=false is prevented.
-It would lead the redirect plugin to override all the page.html files created by Docusaurus.`),
-    );
-    options.fromExtensions = options.fromExtensions.filter(
-      (ext) => ext !== 'html',
-    );
-  }
-
   return {
     name: 'docusaurus-plugin-client-redirects',
-    async postBuild(props: Props) {
+    async postBuild(props) {
       const pluginContext: PluginContext = {
         relativeRoutesPaths: props.routesPaths.map(
           (path) => `${addLeadingSlash(removePrefix(path, props.baseUrl))}`,
@@ -47,14 +31,15 @@ It would lead the redirect plugin to override all the page.html files created by
         baseUrl: props.baseUrl,
         outDir: props.outDir,
         options,
+        siteConfig: props.siteConfig,
       };
 
-      const redirects: RedirectMetadata[] = collectRedirects(
+      const redirects: RedirectItem[] = collectRedirects(
         pluginContext,
         trailingSlash,
       );
 
-      const redirectFiles: RedirectFileMetadata[] = toRedirectFilesMetadata(
+      const redirectFiles: RedirectFile[] = toRedirectFiles(
         redirects,
         pluginContext,
         trailingSlash,
@@ -65,3 +50,6 @@ It would lead the redirect plugin to override all the page.html files created by
     },
   };
 }
+
+export {validateOptions} from './options';
+export type {PluginOptions, Options};

package/src/options.ts

@@ -0,0 +1,75 @@
+/**
+ * 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 {Joi, PathnameSchema} from '@docusaurus/utils-validation';
+import type {OptionValidationContext} from '@docusaurus/types';
+
+export type RedirectOption = {
+  /** Pathname of an existing Docusaurus page */
+  to: string;
+  /** Pathname of the new page(s) we should create */
+  from: string | string[];
+};
+
+export type PluginOptions = {
+  /** Plugin ID. */
+  id: string;
+  /** The extensions to be removed from the route after redirecting. */
+  fromExtensions: string[];
+  /** The extensions to be appended to the route after redirecting. */
+  toExtensions: string[];
+  /** The list of redirect rules, each one with multiple `from`s → one `to`. */
+  redirects: RedirectOption[];
+  /**
+   * A callback to create a redirect rule. Docusaurus query this callback
+   * against every path it has created, and use its return value to output more
+   * paths.
+   * @returns All the paths from which we should redirect to `path`
+   */
+  createRedirects?: (
+    /** An existing Docusaurus route path */
+    path: string,
+  ) => string[] | string | null | undefined;
+};
+
+export type Options = Partial<PluginOptions>;
+
+export const DEFAULT_OPTIONS: Partial<PluginOptions> = {
+  fromExtensions: [],
+  toExtensions: [],
+  redirects: [],
+};
+
+const RedirectPluginOptionValidation = Joi.object<RedirectOption>({
+  to: PathnameSchema.required(),
+  from: Joi.alternatives().try(
+    PathnameSchema.required(),
+    Joi.array().items(PathnameSchema.required()),
+  ),
+});
+
+const isString = Joi.string().required().not(null);
+
+const UserOptionsSchema = Joi.object<PluginOptions>({
+  fromExtensions: Joi.array()
+    .items(isString)
+    .default(DEFAULT_OPTIONS.fromExtensions),
+  toExtensions: Joi.array()
+    .items(isString)
+    .default(DEFAULT_OPTIONS.toExtensions),
+  redirects: Joi.array()
+    .items(RedirectPluginOptionValidation)
+    .default(DEFAULT_OPTIONS.redirects),
+  createRedirects: Joi.function().maxArity(1),
+}).default(DEFAULT_OPTIONS);
+
+export function validateOptions({
+  validate,
+  options: userOptions,
+}: OptionValidationContext<Options | undefined, PluginOptions>): PluginOptions {
+  return validate(UserOptionsSchema, userOptions);
+}

package/src/redirectValidation.ts

@@ -5,15 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {RedirectMetadata} from './types';
 import {Joi, PathnameSchema} from '@docusaurus/utils-validation';
+import type {RedirectItem} from './types';
 
-const RedirectSchema = Joi.object<RedirectMetadata>({
+const RedirectSchema = Joi.object<RedirectItem>({
   from: PathnameSchema.required(),
   to: PathnameSchema.required(),
 });
 
-export function validateRedirect(redirect: RedirectMetadata): void {
+export function validateRedirect(redirect: RedirectItem): void {
   const {error} = RedirectSchema.validate(redirect, {
     abortEarly: true,
     convert: false,

package/src/types.ts

@@ -5,39 +5,25 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import {Props} from '@docusaurus/types';
+import type {Props} from '@docusaurus/types';
+import type {PluginOptions} from './options';
 
-export type PluginOptions = {
-  id: string;
-  fromExtensions: string[];
-  toExtensions: string[];
-  redirects: RedirectOption[];
-  createRedirects?: CreateRedirectsFnOption;
-};
-
-// For a given existing route path,
-// return all the paths from which we should redirect from
-export type CreateRedirectsFnOption = (
-  path: string,
-) => string[] | string | null | undefined;
-
-export type RedirectOption = {
-  to: string;
-  from: string | string[];
-};
-
-export type UserPluginOptions = Partial<PluginOptions>;
-
-// The minimal infos the plugin needs to work
-export type PluginContext = Pick<Props, 'outDir' | 'baseUrl'> & {
+/**
+ * The minimal infos the plugin needs to work
+ */
+export type PluginContext = Pick<Props, 'outDir' | 'baseUrl' | 'siteConfig'> & {
   options: PluginOptions;
   relativeRoutesPaths: string[];
 };
 
-// In-memory representation of redirects we want: easier to test
-// /!\ easy to be confused: "from" is the new page we should create,
-// that redirects to "to": the existing Docusaurus page
-export type RedirectMetadata = {
-  from: string; // pathname
-  to: string; // pathname
+/**
+ * In-memory representation of redirects we want: easier to test
+ * /!\ easy to be confused: "from" is the new page we should create,
+ * that redirects to "to": the existing Docusaurus page
+ */
+export type RedirectItem = {
+  /** Pathname of the new page we should create */
+  from: string;
+  /** Pathname of an existing Docusaurus page */
+  to: string;
 };