@docusaurus/core 3.10.1 → 4.0.0-canary-6808

package/lib/server/configValidation.js

@@ -16,15 +16,14 @@ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const DEFAULT_I18N_LOCALE = 'en';
 const SiteUrlSchema = utils_validation_1.Joi.string()
     .custom((value, helpers) => {
-    try {
-        const { pathname } = new URL(value);
-        if (pathname !== '/') {
-            return helpers.error('docusaurus.subPathError', { pathname });
-        }
-    }
-    catch {
+    const url = URL.parse(value);
+    if (url === null) {
         return helpers.error('any.invalid');
     }
+    const { pathname } = url;
+    if (pathname !== '/') {
+        return helpers.error('docusaurus.subPathError', { pathname });
+    }
     return (0, utils_common_1.removeTrailingSlash)(value);
 })
     .messages({
@@ -70,7 +69,6 @@ exports.DEFAULT_FASTER_CONFIG_TRUE = {
     gitEagerVcs: true,
 };
 exports.DEFAULT_FUTURE_V4_CONFIG = {
-    removeLegacyPostBuildHeadAttribute: false,
     useCssCascadeLayers: false,
     siteStorageNamespacing: false,
     fasterByDefault: false,
@@ -78,7 +76,6 @@ exports.DEFAULT_FUTURE_V4_CONFIG = {
 };
 // When using the "v4: true" shortcut
 exports.DEFAULT_FUTURE_V4_CONFIG_TRUE = {
-    removeLegacyPostBuildHeadAttribute: true,
     useCssCascadeLayers: true,
     siteStorageNamespacing: true,
     fasterByDefault: true,
@@ -93,6 +90,7 @@ exports.DEFAULT_FUTURE_CONFIG = {
 exports.DEFAULT_MARKDOWN_HOOKS = {
     onBrokenMarkdownLinks: 'warn',
     onBrokenMarkdownImages: 'throw',
+    onUnusedMarkdownDirectives: 'warn',
 };
 exports.DEFAULT_MARKDOWN_MDX1COMPAT = {
     comments: true,
@@ -227,7 +225,6 @@ const FASTER_CONFIG_SCHEMA = utils_validation_1.Joi.alternatives()
     .optional();
 const FUTURE_V4_SCHEMA = utils_validation_1.Joi.alternatives()
     .try(utils_validation_1.Joi.object({
-    removeLegacyPostBuildHeadAttribute: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FUTURE_V4_CONFIG.removeLegacyPostBuildHeadAttribute),
     useCssCascadeLayers: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FUTURE_V4_CONFIG.useCssCascadeLayers),
     siteStorageNamespacing: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FUTURE_V4_CONFIG.siteStorageNamespacing),
     fasterByDefault: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FUTURE_V4_CONFIG.fasterByDefault),
@@ -352,7 +349,7 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
             is: utils_validation_1.Joi.valid(true),
             then: utils_validation_1.Joi.optional(),
             otherwise: utils_validation_1.Joi.object()
-                .pattern(/[\w-]+/, utils_validation_1.Joi.string())
+                .pattern(/[\w-]+/, utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.string(), utils_validation_1.Joi.boolean()))
                 .required(),
         }),
         customElement: utils_validation_1.Joi.bool().default(false),
@@ -415,6 +412,9 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
             onBrokenMarkdownImages: utils_validation_1.Joi.alternatives()
                 .try(utils_validation_1.Joi.string().equal('ignore', 'log', 'warn', 'throw'), utils_validation_1.Joi.function())
                 .default(exports.DEFAULT_CONFIG.markdown.hooks.onBrokenMarkdownImages),
+            onUnusedMarkdownDirectives: utils_validation_1.Joi.alternatives()
+                .try(utils_validation_1.Joi.string().equal('ignore', 'log', 'warn', 'throw'), utils_validation_1.Joi.function())
+                .default(exports.DEFAULT_CONFIG.markdown.hooks.onUnusedMarkdownDirectives),
         }).default(exports.DEFAULT_CONFIG.markdown.hooks),
     }).default({
         ...exports.DEFAULT_CONFIG.markdown,
@@ -470,12 +470,6 @@ Please migrate and move this option to code=${'siteConfig.markdown.hooks.onBroke
             : (0, utils_1.getVcsPreset)('disabled');
         config.future.experimental_vcs = vcsConfig;
     }
-    if (config.future.faster.ssgWorkerThreads &&
-        !config.future.v4.removeLegacyPostBuildHeadAttribute) {
-        throw new Error(`Docusaurus config ${logger_1.default.code('future.faster.ssgWorkerThreads')} requires the future flag ${logger_1.default.code('future.v4.removeLegacyPostBuildHeadAttribute')} to be turned on.
-If you use Docusaurus Faster, we recommend that you also activate Docusaurus v4 future flags: ${logger_1.default.code('{future: {v4: true}}')}
-All the v4 future flags are documented here: https://docusaurus.io/docs/api/docusaurus-config#future`);
-    }
     if (config.future.faster.rspackPersistentCache &&
         !config.future.faster.rspackBundler) {
         throw new Error(`Docusaurus config flag ${logger_1.default.code('future.faster.rspackPersistentCache')} requires the flag ${logger_1.default.code('future.faster.rspackBundler')} to be turned on.`);

package/lib/server/getHostPort.js

@@ -69,8 +69,7 @@ Would you like to run the app on another port instead?`),
         return shouldChangePort ? port : null;
     }
     catch (err) {
-        logger_1.default.error `Could not find an open port at ${host}.`;
-        throw err;
+        throw new Error(logger_1.default.interpolate `Could not find an open port at ${host}.`, { cause: err });
     }
 }
 async function getHostPort(options) {

package/lib/server/htmlTags.js

@@ -9,8 +9,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadHtmlTags = loadHtmlTags;
 const tslib_1 = require("tslib");
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
-const html_tags_1 = tslib_1.__importDefault(require("html-tags"));
-const void_1 = tslib_1.__importDefault(require("html-tags/void"));
+const html_tags_1 = tslib_1.__importStar(require("html-tags"));
 const escape_html_1 = tslib_1.__importDefault(require("escape-html"));
 // TODO this should be done at config validation time, not here
 function assertIsHtmlTagObject(val) {
@@ -34,7 +33,7 @@ function hashRouterAbsoluteToRelativeTagAttribute(name, value) {
 }
 function htmlTagObjectToString({ tag, router, }) {
     assertIsHtmlTagObject(tag);
-    const isVoidTag = void_1.default.includes(tag.tagName);
+    const isVoidTag = html_tags_1.voidHtmlTags.includes(tag.tagName);
     const tagAttributes = tag.attributes ?? {};
     const attributes = Object.keys(tagAttributes)
         .map((attr) => {

package/lib/server/i18n.js

@@ -23,7 +23,7 @@ function inferLanguageDisplayName(locale) {
                 fallback: 'code',
             }).of(l);
         }
-        catch (e) {
+        catch {
             // This is to compensate "of()" that is a bit strict
             // Looks like starting Node 22, this locale throws: "en-US-u-ca-buddhist"
             // RangeError: invalid_argument
@@ -64,11 +64,7 @@ function getDefaultDirection(localeStr) {
     const locale = new Intl.Locale(localeStr);
     // see https://github.com/tc39/proposal-intl-locale-info
     // see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/getTextInfo
-    // Node 18.0 implements a former version of the getTextInfo() proposal
-    // TODO Docusaurus v4: remove the fallback to locale.textInfo
-    // @ts-expect-error: The TC39 proposal was updated
-    const textInto = locale.getTextInfo?.() ?? locale.textInfo;
-    return textInto.direction ?? 'ltr';
+    return locale.getTextInfo().direction ?? 'ltr';
 }
 function getDefaultLocaleConfig(
 // Locale "key/identifier"

package/lib/server/plugins/plugins.js

@@ -169,15 +169,7 @@ async function reloadPlugin({ pluginIdentifier, plugins: previousPlugins, contex
             plugin: previousPlugin,
             context,
         });
-        /*
-      // TODO Docusaurus v4 - upgrade to Node 20, use array.with()
-      const plugins = previousPlugins.with(
-        previousPlugins.indexOf(previousPlugin),
-        plugin,
-      );
-       */
-        const plugins = [...previousPlugins];
-        plugins[previousPlugins.indexOf(previousPlugin)] = plugin;
+        const plugins = previousPlugins.with(previousPlugins.indexOf(previousPlugin), plugin);
         const allContentLoadedResult = await executeAllPluginsAllContentLoaded({
             plugins,
             context,

package/lib/server/site.js

@@ -37,7 +37,7 @@ async function loadContext(params) {
     const { siteDir, outDir: baseOutDir = utils_1.DEFAULT_BUILD_DIR_NAME, locale, config: customConfigFilePath, automaticBaseUrlLocalizationDisabled, } = params;
     const generatedFilesDir = path_1.default.resolve(siteDir, utils_1.GENERATED_FILES_DIR_NAME);
     const { siteVersion, loadSiteConfig: { siteConfig: initialSiteConfig, siteConfigPath }, } = await (0, combine_promises_1.default)({
-        siteVersion: (0, siteMetadata_1.loadSiteVersion)(siteDir),
+        siteVersion: (0, siteMetadata_1.tryLoadSitePackageJson)(siteDir).then((pkg) => pkg?.version),
         loadSiteConfig: (0, config_1.loadSiteConfig)({
             siteDir,
             customConfigFilePath,
@@ -78,6 +78,7 @@ async function loadContext(params) {
     const localizationDir = path_1.default.resolve(siteDir, i18n.path, (0, utils_1.getLocaleConfig)(i18n).path);
     const siteConfig = {
         ...initialSiteConfig,
+        url: localeConfig.url,
         baseUrl,
     };
     const codeTranslations = await (0, translations_1.loadSiteCodeTranslations)({ localizationDir });

package/lib/server/siteMetadata.d.ts

@@ -5,9 +5,14 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { LoadedPlugin, PluginVersionInformation, SiteMetadata } from '@docusaurus/types';
-export declare function loadSiteVersion(siteDir: string): Promise<string | undefined>;
+type PackageJson = {
+    name?: string;
+    version?: string;
+};
+export declare function tryLoadSitePackageJson(siteDir: string): Promise<PackageJson | undefined>;
 export declare function loadPluginVersion(pluginPath: string, siteDir: string): Promise<PluginVersionInformation>;
 export declare function createSiteMetadata({ siteVersion, plugins, }: {
     siteVersion: string | undefined;
     plugins: LoadedPlugin[];
 }): SiteMetadata;
+export {};

package/lib/server/siteMetadata.js

@@ -6,26 +6,28 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.loadSiteVersion = loadSiteVersion;
+exports.tryLoadSitePackageJson = tryLoadSitePackageJson;
 exports.loadPluginVersion = loadPluginVersion;
 exports.createSiteMetadata = createSiteMetadata;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const path_1 = tslib_1.__importDefault(require("path"));
 const utils_1 = require("@docusaurus/utils");
-async function loadPackageJsonVersion(packageJsonPath) {
+async function tryLoadPackageJson(packageJsonPath) {
     if (await fs_extra_1.default.pathExists(packageJsonPath)) {
-        // eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
-        return require(packageJsonPath).version;
+        try {
+            return (await fs_extra_1.default.readJSON(packageJsonPath));
+        }
+        catch (error) {
+            throw new Error(`Couldn't load package.json file at ${packageJsonPath}`, {
+                cause: error,
+            });
+        }
     }
     return undefined;
 }
-async function loadPackageJsonName(packageJsonPath) {
-    // eslint-disable-next-line @typescript-eslint/no-var-requires, import/no-dynamic-require, global-require
-    return require(packageJsonPath).name;
-}
-async function loadSiteVersion(siteDir) {
-    return loadPackageJsonVersion(path_1.default.join(siteDir, 'package.json'));
+async function tryLoadSitePackageJson(siteDir) {
+    return tryLoadPackageJson(path_1.default.join(siteDir, 'package.json'));
 }
 async function loadPluginVersion(pluginPath, siteDir) {
     let potentialPluginPackageJsonDirectory = path_1.default.dirname(pluginPath);
@@ -38,10 +40,11 @@ async function loadPluginVersion(pluginPath, siteDir) {
                 // as local plugin.
                 return { type: 'project' };
             }
+            const packageJson = await tryLoadPackageJson(packageJsonPath);
             return {
                 type: 'package',
-                name: await loadPackageJsonName(packageJsonPath),
-                version: await loadPackageJsonVersion(packageJsonPath),
+                name: packageJson?.name,
+                version: packageJson?.version,
             };
         }
         potentialPluginPackageJsonDirectory = path_1.default.dirname(potentialPluginPackageJsonDirectory);

package/lib/server/translations/translations.js

@@ -62,7 +62,7 @@ function mergeTranslationFileContent({ existingContent = {}, newContent, options
             // If messages already exist, we don't override them (unless requested)
             message: options.override
                 ? message
-                : existingContent[key]?.message ?? message,
+                : (existingContent[key]?.message ?? message),
             description,
         };
     });

package/lib/ssg/ssgEnv.js

@@ -9,9 +9,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SSGWorkerThreadRecyclerMaxMemory = exports.SSGWorkerThreadTaskSize = exports.SSGWorkerThreadCount = exports.SSGConcurrency = void 0;
 // Secret way to set SSR plugin async concurrency option
 // Waiting for feedback before documenting this officially?
-// TODO Docusaurus v4, rename SSR => SSG
-exports.SSGConcurrency = process.env.DOCUSAURUS_SSR_CONCURRENCY
-    ? parseInt(process.env.DOCUSAURUS_SSR_CONCURRENCY, 10)
+exports.SSGConcurrency = process.env.DOCUSAURUS_SSG_CONCURRENCY
+    ? parseInt(process.env.DOCUSAURUS_SSG_CONCURRENCY, 10)
     : // Not easy to define a reasonable option default
         // Will still be better than Infinity
         // See also https://github.com/sindresorhus/p-map/issues/24

package/lib/ssg/ssgExecutor.js

@@ -51,11 +51,7 @@ function getNumberOfThreads(pathnames) {
         return ssgEnv_1.SSGWorkerThreadCount;
     }
     // See also https://github.com/tinylibs/tinypool/pull/108
-    const cpuCount = 
-    // TODO Docusaurus v4: bump node, availableParallelism() now always exists
-    typeof os_1.default.availableParallelism === 'function'
-        ? os_1.default.availableParallelism()
-        : os_1.default.cpus().length;
+    const cpuCount = os_1.default.availableParallelism();
     return inferNumberOfThreads({
         pageCount: pathnames.length,
         cpuCount,
@@ -64,6 +60,21 @@ function getNumberOfThreads(pathnames) {
         minPagesPerCpu: 100,
     });
 }
+// Workaround for Node styleText() limitation
+// See https://github.com/nodejs/node/issues/65766
+function getWorkerColorEnv() {
+    // Preserve an explicit user choice
+    if (process.env.FORCE_COLOR !== undefined) {
+        return {};
+    }
+    const depth = process.stdout.isTTY
+        ? (process.stdout.getColorDepth?.() ?? 0)
+        : 0;
+    if (depth > 2) {
+        return { FORCE_COLOR: depth >= 24 ? '3' : depth >= 8 ? '2' : '1' };
+    }
+    return {};
+}
 const createPooledSSGExecutor = async ({ params, pathnames, }) => {
     const numberOfThreads = getNumberOfThreads(pathnames);
     // When the inferred or provided number of threads is just 1
@@ -84,6 +95,12 @@ const createPooledSSGExecutor = async ({ params, pathnames, }) => {
             runtime: 'worker_threads',
             isolateWorkers: false,
             workerData: { params },
+            env: {
+                // Cast is safe
+                // See https://github.com/tinylibs/tinypool/issues/136
+                ...process.env,
+                ...getWorkerColorEnv(),
+            },
             // WORKER MEMORY MANAGEMENT
             // Allows containing SSG memory leaks with a thread recycling workaround
             // See https://github.com/facebook/docusaurus/pull/11166

package/lib/ssg/ssgGlobalResult.js

@@ -17,20 +17,11 @@ function printSSGWarnings(results) {
     if (process.env.DOCUSAURUS_IGNORE_SSG_WARNINGS === 'true') {
         return;
     }
-    const ignoredWarnings = [
-        // TODO Docusaurus v4: remove with React 19 upgrade
-        //  React 18 emit NULL chars, and minifier detects it
-        //  see https://github.com/facebook/docusaurus/issues/9985
-        'Unexpected null character',
-    ];
-    const keepWarning = (warning) => {
-        return !ignoredWarnings.some((iw) => warning.includes(iw));
-    };
     const resultsWithWarnings = results
         .map((success) => {
         return {
             ...success,
-            warnings: success.result.warnings.filter(keepWarning),
+            warnings: success.result.warnings,
         };
     })
         .filter((result) => result.warnings.length > 0);

package/lib/ssg/ssgParams.d.ts

@@ -20,7 +20,6 @@ export type SSGParams = {
     htmlMinifierType: HtmlMinifierType;
     serverBundlePath: string;
     ssgTemplateContent: string;
-    v4RemoveLegacyPostBuildHeadAttribute: boolean;
 };
 export declare function createSSGParams({ props, serverBundlePath, clientManifestPath, }: {
     props: Props;

package/lib/ssg/ssgParams.js

@@ -29,7 +29,6 @@ async function createSSGParams({ props, serverBundlePath, clientManifestPath, })
         htmlMinifierType: props.siteConfig.future.faster.swcHtmlMinimizer
             ? 'swc'
             : 'terser',
-        v4RemoveLegacyPostBuildHeadAttribute: props.siteConfig.future.v4.removeLegacyPostBuildHeadAttribute,
     };
     // Useless but ensures that SSG params remain serializable
     return structuredClone(params);

package/lib/ssg/ssgRenderer.js

@@ -86,7 +86,6 @@ function reduceCollectedData(pageCollectedData) {
         anchors: pageCollectedData.anchors,
         metadata: {
             public: pageCollectedData.metadata.public,
-            helmet: pageCollectedData.metadata.helmet,
         },
         links: pageCollectedData.links,
     };
@@ -94,10 +93,7 @@ function reduceCollectedData(pageCollectedData) {
 async function generateStaticFile({ pathname, appRenderer, params, htmlMinifier, ssgTemplate, }) {
     try {
         // This only renders the app HTML
-        const appRenderResult = await appRenderer.render({
-            pathname,
-            v4RemoveLegacyPostBuildHeadAttribute: params.v4RemoveLegacyPostBuildHeadAttribute,
-        });
+        const appRenderResult = await appRenderer.render({ pathname });
         // This renders the full page HTML, including head tags...
         const fullPageHtml = (0, ssgTemplate_1.renderSSGTemplate)({
             params,

package/lib/ssg/ssgTemplate.js

@@ -9,15 +9,13 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.compileSSGTemplate = compileSSGTemplate;
 exports.renderSSGTemplate = renderSSGTemplate;
 exports.renderHashRouterTemplate = renderHashRouterTemplate;
-const tslib_1 = require("tslib");
-const eta = tslib_1.__importStar(require("eta"));
+const eta_1 = require("eta");
 const react_loadable_ssr_addon_v5_slorber_1 = require("react-loadable-ssr-addon-v5-slorber");
 const logger_1 = require("@docusaurus/logger");
 async function compileSSGTemplate(template) {
-    const compiledTemplate = eta.compile(template.trim(), {
-        rmWhitespace: true,
-    });
-    return (data) => compiledTemplate(data, eta.defaultConfig);
+    const eta = new eta_1.Eta({ rmWhitespace: true });
+    const compiledTemplate = eta.compile(template.trim());
+    return (data) => eta.render(compiledTemplate, data);
 }
 /**
  * Given a list of modules that were SSR an d

package/lib/ssg/ssgWorkerThread.js

@@ -11,7 +11,6 @@ const tslib_1 = require("tslib");
 const node_worker_threads_1 = require("node:worker_threads");
 const logger_1 = tslib_1.__importStar(require("@docusaurus/logger"));
 const ssgRenderer_js_1 = require("./ssgRenderer.js");
-// eslint-disable-next-line no-underscore-dangle
 const workerId = process?.__tinypool_state__?.workerId;
 if (!workerId) {
     throw new Error('SSG Worker Thread not executing in Tinypool context?');

package/lib/webpack/base.js

@@ -87,9 +87,14 @@ async function createBaseConfig({ props, isServer, minify, faster, configureWebp
         }
         if (props.currentBundler.name === 'rspack') {
             if (props.siteConfig.future.faster.rspackPersistentCache) {
-                // Use cache: true + experiments.cache.type: "persistent"
-                // See https://rspack.dev/config/experiments#persistent-cache
-                return true;
+                return {
+                    type: 'persistent',
+                    // Rspack doesn't have "cache.name" like Webpack
+                    // This is not ideal but work around is to merge name/version
+                    // See https://github.com/web-infra-dev/rspack/pull/8920#issuecomment-2658938695
+                    version: `${getCacheName()}-${getCacheVersion()}`,
+                    buildDependencies: getCacheBuildDependencies(),
+                };
             }
             else {
                 return disabledPersistentCacheValue;
@@ -104,29 +109,10 @@ async function createBaseConfig({ props, isServer, minify, faster, configureWebp
             },
         };
     }
-    function getExperiments() {
-        if (props.currentBundler.name === 'rspack') {
-            // TODO find a way to type this
-            const experiments = {};
-            if (!process.env.DOCUSAURUS_NO_PERSISTENT_CACHE) {
-                experiments.cache = {
-                    type: 'persistent',
-                    // Rspack doesn't have "cache.name" like Webpack
-                    // This is not ideal but work around is to merge name/version
-                    // See https://github.com/web-infra-dev/rspack/pull/8920#issuecomment-2658938695
-                    version: `${getCacheName()}-${getCacheVersion()}`,
-                    buildDependencies: getCacheBuildDependencies(),
-                };
-            }
-            return experiments;
-        }
-        return undefined;
-    }
     return {
         mode,
         name,
         cache: getCache(),
-        experiments: getExperiments(),
         output: {
             pathinfo: false,
             path: outDir,
@@ -251,6 +237,10 @@ async function createBaseConfig({ props, isServer, minify, faster, configureWebp
                             // See https://github.com/facebook/docusaurus/pull/10423
                             localIdentName: `[local]_[contenthash:base64:4]`,
                             exportOnlyLocals: isServer,
+                            // Export CSS module class names compatible with css-loader v6
+                            // export ".themedComponent--dark" instead of .themedComponentDark
+                            // See https://github.com/webpack/css-loader/releases/tag/v7.0.0
+                            exportLocalsConvention: 'as-is',
                         },
                         importLoaders: 1,
                         sourceMap: !isProd,

package/lib/webpack/server.js

@@ -35,7 +35,7 @@ async function createServerConfig({ props, configureWebpackUtils, }) {
         output: {
             path: outputDir,
             filename: outputFilename,
-            libraryTarget: 'commonjs2',
+            library: { type: 'commonjs2' },
         },
         plugins: [
             new ProgressBarPlugin({

package/lib/webpack/utils/getHttpsConfig.d.ts

@@ -4,7 +4,13 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export default function getHttpsConfig(): Promise<boolean | {
+type HttpsConfigOptions = {
+    https: boolean;
+    sslCert: string;
+    sslKey: string;
+};
+export default function getHttpsConfig(options?: Partial<HttpsConfigOptions>): Promise<boolean | {
     cert: Buffer;
     key: Buffer;
 }>;
+export {};

package/lib/webpack/utils/getHttpsConfig.js

@@ -13,48 +13,109 @@ const path_1 = tslib_1.__importDefault(require("path"));
 const crypto_1 = tslib_1.__importDefault(require("crypto"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 // Ensure the certificate and key provided are valid and if not
-// throw an easy to debug error
-function validateKeyAndCerts({ cert, key, keyFile, crtFile, }) {
-    let encrypted;
+// throw an easy to debug error.
+//
+// Works for any key type (RSA, ECDSA, EdDSA, ...) — parses both PEMs and
+// checks that the public key embedded in the cert matches the public key
+// derived from the private key.
+function validateKeyAndCerts({ cert, key }) {
+    let certPublicKey;
     try {
-        // publicEncrypt will throw an error with an invalid cert
-        encrypted = crypto_1.default.publicEncrypt(cert, Buffer.from('test'));
+        certPublicKey = new crypto_1.default.X509Certificate(cert.content).publicKey;
     }
-    catch (err) {
-        logger_1.default.error `The certificate path=${crtFile} is invalid.`;
-        throw err;
+    catch (error) {
+        throw new Error(logger_1.default.interpolate `The certificate path=${cert.path} is invalid.`, { cause: error });
     }
+    let keyPublicKey;
     try {
-        // privateDecrypt will throw an error with an invalid key
-        crypto_1.default.privateDecrypt(key, encrypted);
+        keyPublicKey = crypto_1.default.createPublicKey(crypto_1.default.createPrivateKey(key.content));
     }
-    catch (err) {
-        logger_1.default.error `The certificate key path=${keyFile} is invalid.`;
-        throw err;
+    catch (error) {
+        throw new Error(logger_1.default.interpolate `The certificate key path=${key.path} is invalid.`, { cause: error });
     }
+    if (!certPublicKey.equals(keyPublicKey)) {
+        throw new Error(logger_1.default.interpolate `The certificate path=${cert.path} and key path=${key.path} do not match.`);
+    }
+}
+function getExplicitHttps(options) {
+    return (options.https ??
+        (typeof process.env.DOCUSAURUS_HTTPS !== 'undefined'
+            ? process.env.DOCUSAURUS_HTTPS == 'true'
+            : undefined) ??
+        (typeof process.env.HTTPS !== 'undefined'
+            ? process.env.HTTPS == 'true'
+            : undefined));
+}
+async function readCryptoFile(filepath, source) {
+    if (!(await fs_extra_1.default.pathExists(filepath))) {
+        throw new Error(logger_1.default.interpolate `You specified ${source}, but file at path path=${filepath} can't be found.`);
+    }
+    try {
+        return {
+            path: filepath,
+            source,
+            content: await fs_extra_1.default.readFile(filepath),
+        };
+    }
+    catch (error) {
+        throw new Error(logger_1.default.interpolate `You specified ${source}, but file at path path=${filepath} can't be read.`, { cause: error });
+    }
+}
+function getCert(options, cwd) {
+    if (options.sslCert) {
+        return readCryptoFile(path_1.default.resolve(cwd, options.sslCert), 'CLI arg --ssl-cert');
+    }
+    if (process.env.DOCUSAURUS_SSL_CRT_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.DOCUSAURUS_SSL_CRT_FILE), 'env DOCUSAURUS_SSL_CRT_FILE');
+    }
+    if (process.env.SSL_CRT_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.SSL_CRT_FILE), 'env SSL_CRT_FILE');
+    }
+    return null;
+}
+function getKeyFile(options, cwd) {
+    if (options.sslKey) {
+        return readCryptoFile(path_1.default.resolve(cwd, options.sslKey), 'CLI arg --ssl-key');
+    }
+    if (process.env.DOCUSAURUS_SSL_KEY_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.DOCUSAURUS_SSL_KEY_FILE), 'env DOCUSAURUS_SSL_KEY_FILE');
+    }
+    if (process.env.SSL_KEY_FILE) {
+        return readCryptoFile(path_1.default.resolve(cwd, process.env.SSL_KEY_FILE), 'env SSL_KEY_FILE');
+    }
+    return null;
 }
-// Read file and throw an error if it doesn't exist
-async function readEnvFile(file, type) {
-    if (!(await fs_extra_1.default.pathExists(file))) {
-        throw new Error(`You specified ${type} in your env, but the file "${file}" can't be found.`);
+function ensureCertKeyBothProvided(cert, key) {
+    if ((cert || key) && !(cert && key)) {
+        const fileProvided = (cert ?? key);
+        throw new Error(logger_1.default.interpolate `HTTPS support require proving a certificate and key at the same time.
+You only provided a ${cert ? 'certificate' : 'key'} (with ${fileProvided.source}) at path path=${fileProvided.path}.`);
     }
-    return fs_extra_1.default.readFile(file);
 }
 // Get the https config
-// Return cert files if provided in env, otherwise just true or false
-async function getHttpsConfig() {
-    const appDirectory = await fs_extra_1.default.realpath(process.cwd());
-    const { SSL_CRT_FILE, SSL_KEY_FILE, HTTPS } = process.env;
-    const isHttps = HTTPS === 'true';
-    if (isHttps && SSL_CRT_FILE && SSL_KEY_FILE) {
-        const crtFile = path_1.default.resolve(appDirectory, SSL_CRT_FILE);
-        const keyFile = path_1.default.resolve(appDirectory, SSL_KEY_FILE);
-        const config = {
-            cert: await readEnvFile(crtFile, 'SSL_CRT_FILE'),
-            key: await readEnvFile(keyFile, 'SSL_KEY_FILE'),
+// Return cert files if provided via CLI or env, otherwise just true or false.
+// CLI options take precedence over env vars.
+async function getHttpsConfig(options = {}) {
+    const cwd = await fs_extra_1.default.realpath(process.cwd());
+    const [cert, key] = await Promise.all([
+        getCert(options, cwd),
+        getKeyFile(options, cwd),
+    ]);
+    // Providing both cert/key implies HTTPS
+    const inferredHttps = !!(cert && key);
+    const https = getExplicitHttps(options) ?? inferredHttps;
+    if (https && cert && key) {
+        validateKeyAndCerts({
+            cert,
+            key,
+        });
+        return {
+            cert: cert.content,
+            key: key.content,
         };
-        validateKeyAndCerts({ ...config, keyFile, crtFile });
-        return config;
     }
-    return isHttps;
+    ensureCertKeyBothProvided(cert, key);
+    // Apparently we can have https without cert/key (historical)
+    // although I don't know how this works 🤷‍♂️
+    return https;
 }