@docusaurus/core 0.0.0-4799 → 0.0.0-4802

package/lib/commands/build.js

@@ -47,7 +47,8 @@ forceTerminate = true) {
             throw err;
         }
     }
-    const context = await (0, server_1.loadContext)(siteDir, {
+    const context = await (0, server_1.loadContext)({
+        siteDir,
         customOutDir: cliOptions.outDir,
         customConfigFilePath: cliOptions.config,
         locale: cliOptions.locale,
@@ -79,7 +80,8 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
     process.env.BABEL_ENV = 'production';
     process.env.NODE_ENV = 'production';
     logger_1.default.info `name=${`[${locale}]`} Creating an optimized production build...`;
-    const props = await (0, server_1.load)(siteDir, {
+    const props = await (0, server_1.load)({
+        siteDir,
         customOutDir: cliOptions.outDir,
         customConfigFilePath: cliOptions.config,
         locale,

package/lib/commands/commandUtils.js

@@ -7,8 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getCLIOptionPort = exports.getCLIOptionHost = void 0;
-const tslib_1 = require("tslib");
-const choosePort_1 = tslib_1.__importDefault(require("../choosePort"));
+const choosePort_1 = require("../server/choosePort");
 const utils_1 = require("@docusaurus/utils");
 function getCLIOptionHost(hostOption) {
     return hostOption ?? 'localhost';
@@ -16,6 +15,6 @@ function getCLIOptionHost(hostOption) {
 exports.getCLIOptionHost = getCLIOptionHost;
 async function getCLIOptionPort(portOption, host) {
     const basePort = portOption ? parseInt(portOption, 10) : utils_1.DEFAULT_PORT;
-    return (0, choosePort_1.default)(host, basePort);
+    return (0, choosePort_1.choosePort)(host, basePort);
 }
 exports.getCLIOptionPort = getCLIOptionPort;

package/lib/commands/deploy.js

@@ -35,7 +35,8 @@ function shellExecLog(cmd) {
     }
 }
 async function deploy(siteDir, cliOptions = {}) {
-    const { outDir, siteConfig, siteConfigPath } = await (0, server_1.loadContext)(siteDir, {
+    const { outDir, siteConfig, siteConfigPath } = await (0, server_1.loadContext)({
+        siteDir,
         customConfigFilePath: cliOptions.config,
         customOutDir: cliOptions.outDir,
     });

package/lib/commands/external.js

@@ -10,7 +10,7 @@ exports.externalCommand = void 0;
 const server_1 = require("../server");
 const init_1 = require("../server/plugins/init");
 async function externalCommand(cli, siteDir) {
-    const context = await (0, server_1.loadContext)(siteDir);
+    const context = await (0, server_1.loadContext)({ siteDir });
     const plugins = await (0, init_1.initPlugins)(context);
     // Plugin Lifecycle - extendCli.
     plugins.forEach((plugin) => {

package/lib/commands/serve.js

@@ -12,7 +12,7 @@ const http_1 = tslib_1.__importDefault(require("http"));
 const serve_handler_1 = tslib_1.__importDefault(require("serve-handler"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const path_1 = tslib_1.__importDefault(require("path"));
-const server_1 = require("../server");
+const config_1 = require("../server/config");
 const build_1 = require("./build");
 const commandUtils_1 = require("./commandUtils");
 async function serve(siteDir, cliOptions) {
@@ -28,7 +28,7 @@ async function serve(siteDir, cliOptions) {
     if (port === null) {
         process.exit();
     }
-    const { siteConfig: { baseUrl, trailingSlash }, } = await (0, server_1.loadSiteConfig)({
+    const { siteConfig: { baseUrl, trailingSlash }, } = await (0, config_1.loadSiteConfig)({
         siteDir,
         customConfigFilePath: cliOptions.config,
     });

package/lib/commands/start.js

@@ -30,7 +30,8 @@ async function start(siteDir, cliOptions) {
     process.env.BABEL_ENV = 'development';
     logger_1.default.info('Starting the development server...');
     function loadSite() {
-        return (0, server_1.load)(siteDir, {
+        return (0, server_1.load)({
+            siteDir,
             customConfigFilePath: cliOptions.config,
             locale: cliOptions.locale,
             localizePath: undefined, // should this be configurable?

package/lib/commands/swizzle/common.d.ts

@@ -4,8 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { InitializedPlugin, SwizzleAction, SwizzleActionStatus } from '@docusaurus/types';
-import type { NormalizedPluginConfig } from '../../server/plugins/init';
+import type { InitializedPlugin, SwizzleAction, SwizzleActionStatus, NormalizedPluginConfig } from '@docusaurus/types';
 export declare const SwizzleActions: SwizzleAction[];
 export declare const SwizzleActionsStatuses: SwizzleActionStatus[];
 export declare const PartiallySafeHint: string;

package/lib/commands/swizzle/context.js

@@ -11,13 +11,12 @@ const server_1 = require("../../server");
 const init_1 = require("../../server/plugins/init");
 const configs_1 = require("../../server/plugins/configs");
 async function initSwizzleContext(siteDir) {
-    const context = await (0, server_1.loadContext)(siteDir);
+    const context = await (0, server_1.loadContext)({ siteDir });
     const plugins = await (0, init_1.initPlugins)(context);
     const pluginConfigs = await (0, configs_1.loadPluginConfigs)(context);
-    const pluginsNormalized = await (0, init_1.normalizePluginConfigs)(pluginConfigs, context.siteConfigPath);
     return {
         plugins: plugins.map((plugin, pluginIndex) => ({
-            plugin: pluginsNormalized[pluginIndex],
+            plugin: pluginConfigs[pluginIndex],
             instance: plugin,
         })),
     };

package/lib/commands/writeHeadingIds.js

@@ -30,7 +30,7 @@ async function transformMarkdownFile(filepath, options) {
  * transformed
  */
 async function getPathsToWatch(siteDir) {
-    const context = await (0, server_1.loadContext)(siteDir);
+    const context = await (0, server_1.loadContext)({ siteDir });
     const plugins = await (0, init_1.initPlugins)(context);
     return plugins.flatMap((plugin) => plugin?.getPathsToWatch?.() ?? []);
 }

package/lib/commands/writeTranslations.js

@@ -48,7 +48,8 @@ async function writePluginTranslationFiles({ siteDir, plugin, locale, options, }
     }
 }
 async function writeTranslations(siteDir, options) {
-    const context = await (0, server_1.loadContext)(siteDir, {
+    const context = await (0, server_1.loadContext)({
+        siteDir,
         customConfigFilePath: options.config,
         locale: options.locale,
     });

package/lib/server/choosePort.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+/**
+ * Detects if program is running on port, and prompts user to choose another if
+ * port is already being used. This feature was heavily inspired by
+ * create-react-app and uses many of the same utility functions to implement it.
+ */
+export declare function choosePort(host: string, defaultPort: number): Promise<number | null>;

package/lib/{choosePort.js → server/choosePort.js}

@@ -6,17 +6,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.choosePort = void 0;
 const tslib_1 = require("tslib");
-/**
- * This feature was heavily inspired by create-react-app and
- * uses many of the same utility functions to implement it.
- */
 const child_process_1 = require("child_process");
 const detect_port_1 = tslib_1.__importDefault(require("detect-port"));
-const is_root_1 = tslib_1.__importDefault(require("is-root"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const prompts_1 = tslib_1.__importDefault(require("prompts"));
-const isInteractive = process.stdout.isTTY;
 const execOptions = {
     encoding: 'utf8',
     stdio: [
@@ -57,8 +52,9 @@ function getProcessForPort(port) {
     }
 }
 /**
- * Detects if program is running on port and prompts user
- * to choose another if port is already being used
+ * Detects if program is running on port, and prompts user to choose another if
+ * port is already being used. This feature was heavily inspired by
+ * create-react-app and uses many of the same utility functions to implement it.
  */
 async function choosePort(host, defaultPort) {
     try {
@@ -66,7 +62,9 @@ async function choosePort(host, defaultPort) {
         if (port === defaultPort) {
             return port;
         }
-        const message = process.platform !== 'win32' && defaultPort < 1024 && !(0, is_root_1.default)()
+        const isRoot = process.getuid?.() === 0;
+        const isInteractive = process.stdout.isTTY;
+        const message = process.platform !== 'win32' && defaultPort < 1024 && !isRoot
             ? `Admin permissions are required to run a server on a port below 1024.`
             : `Something is already running on port ${defaultPort}.`;
         if (!isInteractive) {
@@ -90,4 +88,4 @@ Would you like to run the app on another port instead?`),
         throw err;
     }
 }
-exports.default = choosePort;
+exports.choosePort = choosePort;

package/lib/server/clientModules.d.ts

@@ -5,4 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { LoadedPlugin } from '@docusaurus/types';
-export declare function loadClientModules(plugins: LoadedPlugin<unknown>[]): string[];
+/**
+ * Runs the `getClientModules` lifecycle. The returned file paths are all
+ * absolute.
+ */
+export declare function loadClientModules(plugins: LoadedPlugin[]): string[];

package/lib/server/clientModules.js

@@ -9,6 +9,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadClientModules = void 0;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
+/**
+ * Runs the `getClientModules` lifecycle. The returned file paths are all
+ * absolute.
+ */
 function loadClientModules(plugins) {
     return plugins.flatMap((plugin) => plugin.getClientModules?.().map((p) => path_1.default.resolve(plugin.path, p)) ??
         []);

package/lib/server/config.d.ts

@@ -4,5 +4,8 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { DocusaurusConfig } from '@docusaurus/types';
-export declare function loadConfig(configPath: string): Promise<DocusaurusConfig>;
+import type { LoadContext } from '@docusaurus/types';
+export declare function loadSiteConfig({ siteDir, customConfigFilePath, }: {
+    siteDir: string;
+    customConfigFilePath?: string;
+}): Promise<Pick<LoadContext, 'siteConfig' | 'siteConfigPath'>>;

package/lib/server/config.js

@@ -6,19 +6,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadConfig = void 0;
+exports.loadSiteConfig = void 0;
 const tslib_1 = require("tslib");
+const path_1 = tslib_1.__importDefault(require("path"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
+const utils_1 = require("@docusaurus/utils");
 const configValidation_1 = require("./configValidation");
-async function loadConfig(configPath) {
-    if (!(await fs_extra_1.default.pathExists(configPath))) {
-        throw new Error(`Config file at "${configPath}" not found.`);
+async function loadSiteConfig({ siteDir, customConfigFilePath, }) {
+    const siteConfigPath = path_1.default.resolve(siteDir, customConfigFilePath ?? utils_1.DEFAULT_CONFIG_FILE_NAME);
+    if (!(await fs_extra_1.default.pathExists(siteConfigPath))) {
+        throw new Error(`Config file at "${siteConfigPath}" not found.`);
     }
-    const importedConfig = (0, import_fresh_1.default)(configPath);
+    const importedConfig = (0, import_fresh_1.default)(siteConfigPath);
     const loadedConfig = typeof importedConfig === 'function'
         ? await importedConfig()
         : await importedConfig;
-    return (0, configValidation_1.validateConfig)(loadedConfig);
+    const siteConfig = (0, configValidation_1.validateConfig)(loadedConfig);
+    return { siteConfig, siteConfigPath };
 }
-exports.loadConfig = loadConfig;
+exports.loadSiteConfig = loadSiteConfig;

package/lib/server/htmlTags.d.ts

@@ -4,5 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { InjectedHtmlTags, LoadedPlugin } from '@docusaurus/types';
-export declare function loadHtmlTags(plugins: LoadedPlugin[]): InjectedHtmlTags;
+import type { Props, LoadedPlugin } from '@docusaurus/types';
+/**
+ * Runs the `injectHtmlTags` lifecycle, and aggregates all plugins' tags into
+ * directly render-able HTML markup.
+ */
+export declare function loadHtmlTags(plugins: LoadedPlugin[]): Pick<Props, 'headTags' | 'preBodyTags' | 'postBodyTags'>;

package/lib/server/htmlTags.js

@@ -47,6 +47,10 @@ function createHtmlTagsString(tags) {
         .map((val) => (typeof val === 'string' ? val : htmlTagObjectToString(val)))
         .join('\n');
 }
+/**
+ * Runs the `injectHtmlTags` lifecycle, and aggregates all plugins' tags into
+ * directly render-able HTML markup.
+ */
 function loadHtmlTags(plugins) {
     const pluginHtmlTags = plugins.map((plugin) => plugin.injectHtmlTags?.({ content: plugin.content }) ?? {});
     const tagTypes = ['headTags', 'preBodyTags', 'postBodyTags'];

package/lib/server/i18n.d.ts

@@ -5,7 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { I18n, DocusaurusConfig, I18nLocaleConfig } from '@docusaurus/types';
+import type { LoadContextOptions } from './index';
 export declare function getDefaultLocaleConfig(locale: string): I18nLocaleConfig;
-export declare function loadI18n(config: DocusaurusConfig, options: {
-    locale?: string;
-}): Promise<I18n>;
+export declare function loadI18n(config: DocusaurusConfig, options: Pick<LoadContextOptions, 'locale'>): Promise<I18n>;

package/lib/server/index.d.ts

@@ -4,19 +4,35 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { DocusaurusConfig, LoadContext, Props } from '@docusaurus/types';
+import type { LoadContext, Props } from '@docusaurus/types';
 export declare type LoadContextOptions = {
+    /** Usually the CWD; can be overridden with command argument. */
+    siteDir: string;
+    /** Can be customized with `--out-dir` option */
     customOutDir?: string;
+    /** Can be customized with `--config` option */
     customConfigFilePath?: string;
+    /** Default is `i18n.defaultLocale` */
     locale?: string;
+    /**
+     * `true` means the paths will have the locale prepended; `false` means they
+     * won't (useful for `yarn build -l zh-Hans` where the output should be
+     * emitted into `build/` instead of `build/zh-Hans/`); `undefined` is like the
+     * "smart" option where only non-default locale paths are localized
+     */
     localizePath?: boolean;
 };
-export declare function loadSiteConfig({ siteDir, customConfigFilePath, }: {
-    siteDir: string;
-    customConfigFilePath?: string;
-}): Promise<{
-    siteConfig: DocusaurusConfig;
-    siteConfigPath: string;
-}>;
-export declare function loadContext(siteDir: string, options?: LoadContextOptions): Promise<LoadContext>;
-export declare function load(siteDir: string, options?: LoadContextOptions): Promise<Props>;
+/**
+ * Loading context is the very first step in site building. Its options are
+ * directly acquired from CLI options. It mainly loads `siteConfig` and the i18n
+ * context (which includes code translations). The `LoadContext` will be passed
+ * to plugin constructors.
+ */
+export declare function loadContext(options: LoadContextOptions): Promise<LoadContext>;
+/**
+ * This is the crux of the Docusaurus server-side. It reads everything it needs—
+ * code translations, config file, plugin modules... Plugins then use their
+ * lifecycles to generate content and other data. It is side-effect-ful because
+ * it generates temp files in the `.docusaurus` folder for the bundler.
+ */
+export declare function load(options: LoadContextOptions): Promise<Props>;

package/lib/server/index.js

@@ -6,36 +6,33 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.load = exports.loadContext = exports.loadSiteConfig = void 0;
+exports.load = exports.loadContext = void 0;
 const tslib_1 = require("tslib");
 const utils_1 = require("@docusaurus/utils");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const path_1 = tslib_1.__importDefault(require("path"));
+const config_1 = require("./config");
 const ssr_html_template_1 = tslib_1.__importDefault(require("../webpack/templates/ssr.html.template"));
 const clientModules_1 = require("./clientModules");
-const config_1 = require("./config");
 const plugins_1 = require("./plugins");
 const routes_1 = require("./routes");
 const htmlTags_1 = require("./htmlTags");
 const siteMetadata_1 = require("./siteMetadata");
-const duplicateRoutes_1 = require("./duplicateRoutes");
 const i18n_1 = require("./i18n");
 const translations_1 = require("./translations/translations");
-async function loadSiteConfig({ siteDir, customConfigFilePath, }) {
-    const siteConfigPath = path_1.default.resolve(siteDir, customConfigFilePath ?? utils_1.DEFAULT_CONFIG_FILE_NAME);
-    const siteConfig = await (0, config_1.loadConfig)(siteConfigPath);
-    return { siteConfig, siteConfigPath };
-}
-exports.loadSiteConfig = loadSiteConfig;
-async function loadContext(siteDir, options = {}) {
-    const { customOutDir, locale, customConfigFilePath } = options;
+/**
+ * Loading context is the very first step in site building. Its options are
+ * directly acquired from CLI options. It mainly loads `siteConfig` and the i18n
+ * context (which includes code translations). The `LoadContext` will be passed
+ * to plugin constructors.
+ */
+async function loadContext(options) {
+    const { siteDir, customOutDir, locale, customConfigFilePath } = options;
     const generatedFilesDir = path_1.default.resolve(siteDir, utils_1.GENERATED_FILES_DIR_NAME);
-    const { siteConfig: initialSiteConfig, siteConfigPath } = await loadSiteConfig({
+    const { siteConfig: initialSiteConfig, siteConfigPath } = await (0, config_1.loadSiteConfig)({
         siteDir,
         customConfigFilePath,
     });
-    const { ssrTemplate } = initialSiteConfig;
-    const baseOutDir = path_1.default.resolve(siteDir, customOutDir ?? utils_1.DEFAULT_BUILD_DIR_NAME);
     const i18n = await (0, i18n_1.loadI18n)(initialSiteConfig, { locale });
     const baseUrl = (0, utils_1.localizePath)({
         path: initialSiteConfig.baseUrl,
@@ -44,7 +41,7 @@ async function loadContext(siteDir, options = {}) {
         pathType: 'url',
     });
     const outDir = (0, utils_1.localizePath)({
-        path: baseOutDir,
+        path: path_1.default.resolve(siteDir, customOutDir ?? utils_1.DEFAULT_BUILD_DIR_NAME),
         i18n,
         options,
         pathType: 'fs',
@@ -64,20 +61,33 @@ async function loadContext(siteDir, options = {}) {
         outDir,
         baseUrl,
         i18n,
-        ssrTemplate: ssrTemplate ?? ssr_html_template_1.default,
+        ssrTemplate: siteConfig.ssrTemplate ?? ssr_html_template_1.default,
         codeTranslations,
     };
 }
 exports.loadContext = loadContext;
-async function load(siteDir, options = {}) {
-    // Context.
-    const context = await loadContext(siteDir, options);
-    const { generatedFilesDir, siteConfig, siteConfigPath, outDir, baseUrl, i18n, ssrTemplate, codeTranslations, } = context;
-    // Plugins.
+/**
+ * This is the crux of the Docusaurus server-side. It reads everything it needs—
+ * code translations, config file, plugin modules... Plugins then use their
+ * lifecycles to generate content and other data. It is side-effect-ful because
+ * it generates temp files in the `.docusaurus` folder for the bundler.
+ */
+async function load(options) {
+    const { siteDir } = options;
+    const context = await loadContext(options);
+    const { generatedFilesDir, siteConfig, siteConfigPath, outDir, baseUrl, i18n, ssrTemplate, codeTranslations: siteCodeTranslations, } = context;
     const { plugins, pluginsRouteConfigs, globalData, themeConfigTranslated } = await (0, plugins_1.loadPlugins)(context);
     // Side-effect to replace the untranslated themeConfig by the translated one
     context.siteConfig.themeConfig = themeConfigTranslated;
-    (0, duplicateRoutes_1.handleDuplicateRoutes)(pluginsRouteConfigs, siteConfig.onDuplicateRoutes);
+    const clientModules = (0, clientModules_1.loadClientModules)(plugins);
+    const { headTags, preBodyTags, postBodyTags } = (0, htmlTags_1.loadHtmlTags)(plugins);
+    const { registry, routesChunkNames, routesConfig, routesPaths } = await (0, routes_1.loadRoutes)(pluginsRouteConfigs, baseUrl, siteConfig.onDuplicateRoutes);
+    const codeTranslations = {
+        ...(await (0, translations_1.getPluginsDefaultCodeTranslationMessages)(plugins)),
+        ...siteCodeTranslations,
+    };
+    const siteMetadata = await (0, siteMetadata_1.loadSiteMetadata)({ plugins, siteDir });
+    // === Side-effects part ===
     const genWarning = (0, utils_1.generate)(generatedFilesDir, 'DONT-EDIT-THIS-FOLDER', `This folder stores temp files that Docusaurus' client bundler accesses.
 
 DO NOT hand-modify files in this folder because they will be overwritten in the
@@ -93,8 +103,6 @@ next build. You can clear all build artifacts (including this folder) with the
  */
 export default ${JSON.stringify(siteConfig, null, 2)};
 `);
-    // Load client modules.
-    const clientModules = (0, clientModules_1.loadClientModules)(plugins);
     const genClientModules = (0, utils_1.generate)(generatedFilesDir, 'client-modules.js', `export default [
 ${clientModules
         // import() is async so we use require() because client modules can have
@@ -103,10 +111,6 @@ ${clientModules
         .join('\n')}
 ];
 `);
-    // Load extra head & body html tags.
-    const { headTags, preBodyTags, postBodyTags } = (0, htmlTags_1.loadHtmlTags)(plugins);
-    // Routing.
-    const { registry, routesChunkNames, routesConfig, routesPaths } = await (0, routes_1.loadRoutes)(pluginsRouteConfigs, baseUrl);
     const genRegistry = (0, utils_1.generate)(generatedFilesDir, 'registry.js', `export default {
 ${Object.entries(registry)
         .sort((a, b) => a[0].localeCompare(b[0]))
@@ -117,13 +121,7 @@ ${Object.entries(registry)
     const genRoutes = (0, utils_1.generate)(generatedFilesDir, 'routes.js', routesConfig);
     const genGlobalData = (0, utils_1.generate)(generatedFilesDir, 'globalData.json', JSON.stringify(globalData, null, 2));
     const genI18n = (0, utils_1.generate)(generatedFilesDir, 'i18n.json', JSON.stringify(i18n, null, 2));
-    const codeTranslationsWithFallbacks = {
-        ...(await (0, translations_1.getPluginsDefaultCodeTranslationMessages)(plugins)),
-        ...codeTranslations,
-    };
-    const genCodeTranslations = (0, utils_1.generate)(generatedFilesDir, 'codeTranslations.json', JSON.stringify(codeTranslationsWithFallbacks, null, 2));
-    // Version metadata.
-    const siteMetadata = await (0, siteMetadata_1.loadSiteMetadata)({ plugins, siteDir });
+    const genCodeTranslations = (0, utils_1.generate)(generatedFilesDir, 'codeTranslations.json', JSON.stringify(codeTranslations, null, 2));
     const genSiteMetadata = (0, utils_1.generate)(generatedFilesDir, 'site-metadata.json', JSON.stringify(siteMetadata, null, 2));
     await Promise.all([
         genWarning,
@@ -137,7 +135,7 @@ ${Object.entries(registry)
         genI18n,
         genCodeTranslations,
     ]);
-    const props = {
+    return {
         siteConfig,
         siteConfigPath,
         siteMetadata,
@@ -155,6 +153,5 @@ ${Object.entries(registry)
         ssrTemplate,
         codeTranslations,
     };
-    return props;
 }
 exports.load = load;

package/lib/server/plugins/configs.d.ts

@@ -4,5 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { LoadContext, PluginConfig } from '@docusaurus/types';
-export declare function loadPluginConfigs(context: LoadContext): Promise<PluginConfig[]>;
+import type { LoadContext, NormalizedPluginConfig } from '@docusaurus/types';
+/**
+ * Reads the site config's `presets`, `themes`, and `plugins`, imports them, and
+ * normalizes the return value. Plugin configs are ordered, mostly for theme
+ * alias shadowing. Site themes have the highest priority, and preset plugins
+ * are the lowest.
+ */
+export declare function loadPluginConfigs(context: LoadContext): Promise<NormalizedPluginConfig[]>;

package/lib/server/plugins/configs.js

@@ -7,21 +7,79 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadPluginConfigs = void 0;
+const tslib_1 = require("tslib");
 const module_1 = require("module");
+const import_fresh_1 = tslib_1.__importDefault(require("import-fresh"));
 const presets_1 = require("./presets");
-const moduleShorthand_1 = require("../moduleShorthand");
+const moduleShorthand_1 = require("./moduleShorthand");
+async function normalizePluginConfig(pluginConfig, configPath, pluginRequire) {
+    // plugins: ["./plugin"]
+    if (typeof pluginConfig === 'string') {
+        const pluginModuleImport = pluginConfig;
+        const pluginPath = pluginRequire.resolve(pluginModuleImport);
+        const pluginModule = (0, import_fresh_1.default)(pluginPath);
+        return {
+            plugin: pluginModule?.default ?? pluginModule,
+            options: {},
+            pluginModule: {
+                path: pluginModuleImport,
+                module: pluginModule,
+            },
+            entryPath: pluginPath,
+        };
+    }
+    // plugins: [() => {...}]
+    if (typeof pluginConfig === 'function') {
+        return {
+            plugin: pluginConfig,
+            options: {},
+            entryPath: configPath,
+        };
+    }
+    // plugins: [
+    //   ["./plugin",options],
+    // ]
+    if (typeof pluginConfig[0] === 'string') {
+        const pluginModuleImport = pluginConfig[0];
+        const pluginPath = pluginRequire.resolve(pluginModuleImport);
+        const pluginModule = (0, import_fresh_1.default)(pluginPath);
+        return {
+            plugin: pluginModule?.default ?? pluginModule,
+            options: pluginConfig[1],
+            pluginModule: {
+                path: pluginModuleImport,
+                module: pluginModule,
+            },
+            entryPath: pluginPath,
+        };
+    }
+    // plugins: [
+    //   [() => {...}, options],
+    // ]
+    return {
+        plugin: pluginConfig[0],
+        options: pluginConfig[1],
+        entryPath: configPath,
+    };
+}
+/**
+ * Reads the site config's `presets`, `themes`, and `plugins`, imports them, and
+ * normalizes the return value. Plugin configs are ordered, mostly for theme
+ * alias shadowing. Site themes have the highest priority, and preset plugins
+ * are the lowest.
+ */
 async function loadPluginConfigs(context) {
     const preset = await (0, presets_1.loadPresets)(context);
     const { siteConfig, siteConfigPath } = context;
-    const require = (0, module_1.createRequire)(siteConfigPath);
+    const pluginRequire = (0, module_1.createRequire)(siteConfigPath);
     function normalizeShorthand(pluginConfig, pluginType) {
         if (typeof pluginConfig === 'string') {
-            return (0, moduleShorthand_1.resolveModuleName)(pluginConfig, require, pluginType);
+            return (0, moduleShorthand_1.resolveModuleName)(pluginConfig, pluginRequire, pluginType);
         }
         else if (Array.isArray(pluginConfig) &&
             typeof pluginConfig[0] === 'string') {
             return [
-                (0, moduleShorthand_1.resolveModuleName)(pluginConfig[0], require, pluginType),
+                (0, moduleShorthand_1.resolveModuleName)(pluginConfig[0], pluginRequire, pluginType),
                 pluginConfig[1] ?? {},
             ];
         }
@@ -31,12 +89,13 @@ async function loadPluginConfigs(context) {
     preset.themes = preset.themes.map((theme) => normalizeShorthand(theme, 'theme'));
     const standalonePlugins = siteConfig.plugins.map((plugin) => normalizeShorthand(plugin, 'plugin'));
     const standaloneThemes = siteConfig.themes.map((theme) => normalizeShorthand(theme, 'theme'));
-    return [
+    const pluginConfigs = [
         ...preset.plugins,
         ...preset.themes,
         // Site config should be the highest priority.
         ...standalonePlugins,
         ...standaloneThemes,
     ];
+    return Promise.all(pluginConfigs.map((pluginConfig) => normalizePluginConfig(pluginConfig, context.siteConfigPath, pluginRequire)));
 }
 exports.loadPluginConfigs = loadPluginConfigs;

package/lib/server/plugins/index.d.ts

@@ -5,6 +5,10 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { LoadContext, RouteConfig, GlobalData, ThemeConfig, LoadedPlugin } from '@docusaurus/types';
+/**
+ * Initializes the plugins, runs `loadContent`, `translateContent`,
+ * `contentLoaded`, and `translateThemeConfig`.
+ */
 export declare function loadPlugins(context: LoadContext): Promise<{
     plugins: LoadedPlugin[];
     pluginsRouteConfigs: RouteConfig[];