@docusaurus/core 3.10.1 → 3.10.2

package/lib/client/BaseUrlIssueBanner/index.js

@@ -53,7 +53,7 @@ function insertBanner() {
   var suggestedBaseUrl = actualHomePagePath.substr(-1) === '/'
         ? actualHomePagePath
         : actualHomePagePath + '/';
-  suggestionContainer.innerHTML = suggestedBaseUrl;
+  suggestionContainer.textContent = suggestedBaseUrl;
 }
 `;
 }

package/lib/commands/cli.js

@@ -109,6 +109,21 @@ async function createCLIProgram({ cli, cliArgs, siteDir, config, }) {
         .option('--no-open', 'do not open page in the browser (default: false)')
         .option('--poll [interval]', 'use polling rather than watching for reload (default: false). Can specify a poll interval in milliseconds', normalizePollValue)
         .option('--no-minify', 'build website without minimizing JS bundles (default: false)')
+        /*
+        TODO
+        .option(
+          '--https',
+          'serve the dev site over HTTPS using a self-signed cert (default: false). Preferred over the HTTPS=true env var. Implied when both --ssl-cert and --ssl-key are provided.',
+        )
+        .option(
+          '--ssl-cert <path>',
+          'path to a TLS certificate file (implies HTTPS). Preferred over the SSL_CRT_FILE env var; CLI takes precedence if both are set.',
+        )
+        .option(
+          '--ssl-key <path>',
+          'path to a TLS private key file (implies HTTPS). Preferred over the SSL_KEY_FILE env var; CLI takes precedence if both are set.',
+        )
+        */
         .action(start_1.start);
     cli
         .command('serve [siteDir]')

package/lib/commands/serve.js

@@ -19,6 +19,7 @@ const openBrowser_1 = tslib_1.__importDefault(require("./utils/openBrowser/openB
 const config_1 = require("../server/config");
 const build_1 = require("./build/build");
 const getHostPort_1 = require("../server/getHostPort");
+const listenToServer_1 = require("./utils/listenToServer");
 function redirect(res, location) {
     res.writeHead(302, {
         Location: location,
@@ -84,7 +85,7 @@ async function serve(siteDirParam = '.', cliOptions = {}) {
     });
     const url = servingUrl + baseUrl;
     logger_1.default.success `Serving path=${buildDir} directory at: url=${url}`;
-    server.listen(port);
+    await (0, listenToServer_1.listenToServer)({ server, host, port });
     if (cliOptions.open && !process.env.CI) {
         await (0, openBrowser_1.default)(url);
     }

package/lib/commands/start/webpack.js

@@ -41,7 +41,15 @@ function registerWebpackE2ETestHook(compiler) {
 async function createDevServerConfig({ cliOptions, props, host, port, }) {
     const { baseUrl, siteDir, siteConfig } = props;
     const pollingOptions = (0, watcher_1.createPollingOptions)(cliOptions);
-    const httpsConfig = await (0, getHttpsConfig_1.default)();
+    const httpsConfig = await (0, getHttpsConfig_1.default)({
+    /*
+    TODO Docusaurus v4: wire new CLI parameters
+    https: cliOptions.https,
+    sslCert: cliOptions.sslCert,
+    sslKey: cliOptions.sslKey,
+
+     */
+    });
     // https://webpack.js.org/configuration/dev-server
     return {
         hot: cliOptions.hotOnly ? 'only' : true,

package/lib/commands/utils/listenToServer.d.ts

@@ -0,0 +1,5 @@
+export declare function listenToServer({ server, port, host, }: {
+    server: import('node:http').Server;
+    port: number;
+    host: string;
+}): Promise<void>;

package/lib/commands/utils/listenToServer.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listenToServer = listenToServer;
+/**
+ * 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.
+ */
+const logger_1 = require("@docusaurus/logger");
+async function listenToServer({ server, port, host, }) {
+    return new Promise((resolve, reject) => {
+        server.once('listening', () => resolve());
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                reject(new Error(logger_1.logger.interpolate `Address in use, another server is already listening on the requested port number=${port} and host name=${host}`, { cause: err }));
+            }
+            else {
+                reject(err);
+            }
+        });
+        server.listen(port, host);
+    });
+}

package/lib/server/configValidation.js

@@ -352,7 +352,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),

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/site.js

@@ -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/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;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "3.10.1",
+  "version": "3.10.2",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -33,13 +33,13 @@
     "url": "https://github.com/facebook/docusaurus/issues"
   },
   "dependencies": {
-    "@docusaurus/babel": "3.10.1",
-    "@docusaurus/bundler": "3.10.1",
-    "@docusaurus/logger": "3.10.1",
-    "@docusaurus/mdx-loader": "3.10.1",
-    "@docusaurus/utils": "3.10.1",
-    "@docusaurus/utils-common": "3.10.1",
-    "@docusaurus/utils-validation": "3.10.1",
+    "@docusaurus/babel": "3.10.2",
+    "@docusaurus/bundler": "3.10.2",
+    "@docusaurus/logger": "3.10.2",
+    "@docusaurus/mdx-loader": "3.10.2",
+    "@docusaurus/utils": "3.10.2",
+    "@docusaurus/utils-common": "3.10.2",
+    "@docusaurus/utils-validation": "3.10.2",
     "boxen": "^6.2.1",
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
@@ -47,7 +47,7 @@
     "combine-promises": "^1.1.0",
     "commander": "^5.1.0",
     "core-js": "^3.31.1",
-    "detect-port": "^1.5.1",
+    "detect-port": "^2.1.0",
     "escape-html": "^1.0.3",
     "eta": "^2.2.0",
     "eval": "^0.1.8",
@@ -77,10 +77,9 @@
     "webpack-merge": "^6.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.10.1",
-    "@docusaurus/types": "3.10.1",
+    "@docusaurus/module-type-aliases": "3.10.2",
+    "@docusaurus/types": "3.10.2",
     "@total-typescript/shoehorn": "^0.1.2",
-    "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^19.2.3",
     "@types/react-router-config": "^5.0.7",
     "@types/serve-handler": "^6.1.4",
@@ -104,5 +103,5 @@
   "engines": {
     "node": ">=20.0"
   },
-  "gitHead": "41c1a458ecb07d61b6df2761ea4bc1b13db49d12"
+  "gitHead": "f37f9035584917a97a260b91fc2842cba4f8b94f"
 }