feat: shorthands for themes/plugins/presets configuration

packages/docusaurus-types/src/index.d.ts

@@ -322,6 +322,8 @@ export type ConfigureWebpackFn = Plugin<unknown>['configureWebpack'];
 export type ConfigureWebpackFnMergeStrategy = Record<string, MergeStrategy>;
 export type ConfigurePostCssFn = Plugin<unknown>['configurePostCss'];
 
+export type PluginType = 'plugin' | 'theme';
+
 export type PluginOptions = {id?: string} & Record<string, unknown>;
 
 export type PluginConfig =
@@ -331,6 +333,10 @@ export type PluginConfig =
   | [PluginModule, PluginOptions]
   | PluginModule;
 
+export type PluginConfigs = {
+  [type in PluginType]: PluginConfig[];
+};
+
 export interface ChunkRegistry {
   loader: string;
   modulePath: string;

packages/docusaurus/src/commands/swizzle.ts

@@ -148,10 +148,11 @@ export default async function swizzle(
   danger?: boolean,
 ): Promise<void> {
   const context = await loadContext(siteDir);
-  const pluginConfigs = loadPluginConfigs(context);
+  const rawPluginConfigs = loadPluginConfigs(context);
+  const pluginConfigs = [...rawPluginConfigs.plugin, ...rawPluginConfigs.theme];
   const pluginNames = getPluginNames(pluginConfigs);
   const plugins = initPlugins({
-    pluginConfigs,
+    pluginConfigs: rawPluginConfigs,
     context,
   });
   const themeNames = pluginNames.filter((_, index) =>

packages/docusaurus/src/server/index.ts

@@ -26,7 +26,7 @@ import {
   HtmlTagObject,
   LoadContext,
   LoadedPlugin,
-  PluginConfig,
+  PluginConfigs,
   Props,
 } from '@docusaurus/types';
 import {loadHtmlTags} from './html-tags';
@@ -127,16 +127,21 @@ export async function loadContext(
   };
 }
 
-export function loadPluginConfigs(context: LoadContext): PluginConfig[] {
+export function loadPluginConfigs(context: LoadContext): PluginConfigs {
   const {plugins: presetPlugins, themes: presetThemes} = loadPresets(context);
   const {siteConfig} = context;
-  return [
-    ...presetPlugins,
-    ...presetThemes,
-    // Site config should be the highest priority.
-    ...(siteConfig.plugins || []),
-    ...(siteConfig.themes || []),
-  ];
+  return {
+    plugin: [
+      ...presetPlugins,
+      // Site config should be the highest priority.
+      ...(siteConfig.plugins || []),
+    ],
+    theme: [
+      ...presetThemes,
+      // Site config should be the highest priority.
+      ...(siteConfig.themes || []),
+    ],
+  };
 }
 
 // Make a fake plugin to:
@@ -255,7 +260,7 @@ export async function load(
     codeTranslations,
   } = context;
   // Plugins.
-  const pluginConfigs: PluginConfig[] = loadPluginConfigs(context);
+  const pluginConfigs: PluginConfigs = loadPluginConfigs(context);
   const {plugins, pluginsRouteConfigs, globalData, themeConfigTranslated} =
     await loadPlugins({pluginConfigs, context});
 

packages/docusaurus/src/server/plugins/index.ts

@@ -10,7 +10,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import {
   LoadContext,
-  PluginConfig,
+  PluginConfigs,
   PluginContentLoadedActions,
   RouteConfig,
   AllContent,
@@ -70,7 +70,7 @@ export async function loadPlugins({
   pluginConfigs,
   context,
 }: {
-  pluginConfigs: PluginConfig[];
+  pluginConfigs: PluginConfigs;
   context: LoadContext;
 }): Promise<{
   plugins: LoadedPlugin[];

packages/docusaurus/src/server/plugins/init.ts

@@ -15,6 +15,8 @@ import {
   PluginConfig,
   PluginOptions,
   InitializedPlugin,
+  PluginType,
+  PluginConfigs,
 } from '@docusaurus/types';
 import {DEFAULT_PLUGIN_ID} from '../../constants';
 import {getPluginVersion} from '../versions';
@@ -34,15 +36,63 @@ type NormalizedPluginConfig = {
   };
 };
 
+function loadPluginModule(
+  pluginModuleImport: string,
+  pluginRequire: NodeRequire,
+): ImportedPluginModule | undefined {
+  try {
+    const pluginPath = pluginRequire.resolve(pluginModuleImport);
+    return importFresh<ImportedPluginModule>(pluginPath);
+  } catch (e) {
+    return undefined;
+  }
+}
+
+function resolvePluginModule(
+  pluginModuleImport: string,
+  pluginRequire: NodeRequire,
+  pluginType: PluginType,
+): ImportedPluginModule {
+  const loadedPluginModules = [
+    `docusaurus-${pluginType}-${pluginModuleImport}`,
+    `@docusaurus/${pluginType}-${pluginModuleImport}`,
+    `@${pluginModuleImport}/docusaurus-${pluginType}`,
+    pluginModuleImport,
+  ]
+    .map((pluginModuleImportAttempt) =>
+      loadPluginModule(pluginModuleImportAttempt, pluginRequire),
+    )
+    .filter(
+      (pluginModule) => pluginModule !== undefined,
+    ) as ImportedPluginModule[];
+
+  if (loadedPluginModules.length === 0) {
+    throw new Error(
+      `Docusaurus was unable to resolve the ${pluginModuleImport} ${pluginType}. Make sure one of the following packages are installed:\n${loadedPluginModules.map(
+        (pluginModuleImportAttempt) => `* ${pluginModuleImportAttempt}\n`,
+      )}`,
+    );
+  }
+
+  return loadedPluginModules[0];
+}
+
 function normalizePluginConfig(
   pluginConfig: PluginConfig,
   pluginRequire: NodeRequire,
+  pluginType: PluginType,
 ): NormalizedPluginConfig {
-  // plugins: ['./plugin']
+  // plugins: ['./{plugin}']
+  // plugins: ['docusaurus-plugin-{plugin}']
+  // plugins: ['@docusaurus/plugin-{plugin}']
+  // plugins: ['@{company}/docusaurus-plugin']
   if (typeof pluginConfig === 'string') {
     const pluginModuleImport = pluginConfig;
-    const pluginPath = pluginRequire.resolve(pluginModuleImport);
-    const pluginModule = importFresh<ImportedPluginModule>(pluginPath);
+    const pluginModule = resolvePluginModule(
+      pluginModuleImport,
+      pluginRequire,
+      pluginType,
+    );
     return {
       plugin: pluginModule?.default ?? pluginModule,
       options: {},
@@ -128,7 +178,7 @@ export default function initPlugins({
   pluginConfigs,
   context,
 }: {
-  pluginConfigs: PluginConfig[];
+  pluginConfigs: PluginConfigs;
   context: LoadContext;
 }): InitializedPlugin[] {
   // We need to resolve plugins from the perspective of the siteDir, since the siteDir's package.json
@@ -184,36 +234,41 @@ export default function initPlugins({
     }
   }
 
-  const plugins: InitializedPlugin[] = pluginConfigs
-    .map((pluginConfig) => {
-      if (!pluginConfig) {
-        return null;
-      }
-      const normalizedPluginConfig = normalizePluginConfig(
-        pluginConfig,
-        pluginRequire,
-      );
-      const pluginVersion: DocusaurusPluginVersionInformation =
-        doGetPluginVersion(normalizedPluginConfig);
-      const pluginOptions = doValidatePluginOptions(normalizedPluginConfig);
-
-      // Side-effect: merge the normalized theme config in the original one
-      context.siteConfig.themeConfig = {
-        ...context.siteConfig.themeConfig,
-        ...doValidateThemeConfig(normalizedPluginConfig),
-      };
+  const pluginTypes = ['theme', 'plugin'] as PluginType[];
 
-      const pluginInstance = normalizedPluginConfig.plugin(
-        context,
-        pluginOptions,
-      );
+  const plugins: InitializedPlugin[] = pluginTypes
+    .flatMap((pluginType: PluginType) =>
+      pluginConfigs[pluginType].map((pluginConfig) => {
+        if (!pluginConfig) {
+          return null;
+        }
+        const normalizedPluginConfig = normalizePluginConfig(
+          pluginConfig,
+          pluginRequire,
+          pluginType,
+        );
+        const pluginVersion: DocusaurusPluginVersionInformation =
+          doGetPluginVersion(normalizedPluginConfig);
+        const pluginOptions = doValidatePluginOptions(normalizedPluginConfig);
 
-      return {
-        ...pluginInstance,
-        options: pluginOptions,
-        version: pluginVersion,
-      };
-    })
+        // Side-effect: merge the normalized theme config in the original one
+        context.siteConfig.themeConfig = {
+          ...context.siteConfig.themeConfig,
+          ...doValidateThemeConfig(normalizedPluginConfig),
+        };
+
+        const pluginInstance = normalizedPluginConfig.plugin(
+          context,
+          pluginOptions,
+        );
+
+        return {
+          ...pluginInstance,
+          options: pluginOptions,
+          version: pluginVersion,
+        };
+      }),
+    )
     .filter(<T>(item: T): item is Exclude<T, null> => Boolean(item));
 
   ensureUniquePluginInstanceIds(plugins);