@docusaurus/core 2.0.0-beta.1decd6f80 → 2.0.0-beta.20

package/lib/server/brokenLinks.js

@@ -6,57 +6,54 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.handleBrokenLinks = exports.filterExistingFileLinks = exports.getBrokenLinksErrorMessage = exports.getAllBrokenLinks = void 0;
+exports.handleBrokenLinks = void 0;
 const tslib_1 = require("tslib");
 const react_router_config_1 = require("react-router-config");
-const resolve_pathname_1 = tslib_1.__importDefault(require("resolve-pathname"));
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const lodash_1 = require("lodash");
+const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const utils_1 = require("@docusaurus/utils");
 const utils_2 = require("./utils");
 const path_1 = tslib_1.__importDefault(require("path"));
-function toReactRouterRoutes(routes) {
-    // @ts-expect-error: types incompatible???
-    return routes;
-}
+const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 // matchRoutes does not support qs/anchors, so we remove it!
 function onlyPathname(link) {
     return link.split('#')[0].split('?')[0];
 }
 function getPageBrokenLinks({ pagePath, pageLinks, routes, }) {
-    // ReactRouter is able to support links like ./../somePath
-    // but matchRoutes does not do this resolving internally
-    // we must resolve the links before using matchRoutes
-    // resolvePathname is used internally by ReactRouter
+    // ReactRouter is able to support links like ./../somePath but `matchRoutes`
+    // does not do this resolution internally. We must resolve the links before
+    // using `matchRoutes`. `resolvePathname` is used internally by React Router
     function resolveLink(link) {
-        const resolvedLink = resolve_pathname_1.default(onlyPathname(link), pagePath);
+        const resolvedLink = (0, utils_1.resolvePathname)(onlyPathname(link), pagePath);
         return { link, resolvedLink };
     }
     function isBrokenLink(link) {
         const matchedRoutes = [link, decodeURI(link)]
-            .map((l) => react_router_config_1.matchRoutes(toReactRouterRoutes(routes), l))
-            .reduce((prev, cur) => prev.concat(cur));
+            // @ts-expect-error: React router types RouteConfig with an actual React
+            // component, but we load route components with string paths.
+            // We don't actually access component here, so it's fine.
+            .map((l) => (0, react_router_config_1.matchRoutes)(routes, l))
+            .flat();
         return matchedRoutes.length === 0;
     }
     return pageLinks.map(resolveLink).filter((l) => isBrokenLink(l.resolvedLink));
 }
-// The route defs can be recursive, and have a parent match-all route
-// We don't want to match broken links like /docs/brokenLink against /docs/*
-// For this reason, we only consider the "final routes", that do not have subroutes
-// We also need to remove the match all 404 route
+/**
+ * The route defs can be recursive, and have a parent match-all route. We don't
+ * want to match broken links like /docs/brokenLink against /docs/*. For this
+ * reason, we only consider the "final routes" that do not have subroutes.
+ * We also need to remove the match-all 404 route
+ */
 function filterIntermediateRoutes(routesInput) {
     const routesWithout404 = routesInput.filter((route) => route.path !== '*');
-    return utils_2.getAllFinalRoutes(routesWithout404);
+    return (0, utils_2.getAllFinalRoutes)(routesWithout404);
 }
 function getAllBrokenLinks({ allCollectedLinks, routes, }) {
     const filteredRoutes = filterIntermediateRoutes(routes);
-    const allBrokenLinks = lodash_1.mapValues(allCollectedLinks, (pageLinks, pagePath) => {
-        return getPageBrokenLinks({ pageLinks, pagePath, routes: filteredRoutes });
-    });
-    // remove pages without any broken link
-    return lodash_1.pickBy(allBrokenLinks, (brokenLinks) => brokenLinks.length > 0);
+    const allBrokenLinks = lodash_1.default.mapValues(allCollectedLinks, (pageLinks, pagePath) => getPageBrokenLinks({ pageLinks, pagePath, routes: filteredRoutes }));
+    return lodash_1.default.pickBy(allBrokenLinks, (brokenLinks) => brokenLinks.length > 0);
 }
-exports.getAllBrokenLinks = getAllBrokenLinks;
 function getBrokenLinksErrorMessage(allBrokenLinks) {
     if (Object.keys(allBrokenLinks).length === 0) {
         return undefined;
@@ -66,16 +63,20 @@ function getBrokenLinksErrorMessage(allBrokenLinks) {
         return `${brokenLink.link}${showResolvedLink ? ` (resolved as: ${brokenLink.resolvedLink})` : ''}`;
     }
     function pageBrokenLinksMessage(pagePath, brokenLinks) {
-        return `\n- On source page path = ${pagePath}:\n   -> linking to ${brokenLinks
+        return `
+- On source page path = ${pagePath}:
+   -> linking to ${brokenLinks
             .map(brokenLinkMessage)
             .join('\n   -> linking to ')}`;
     }
-    // If there's a broken link appearing very often, it is probably a broken link on the layout!
-    // Add an additional message in such case to help user figure this out.
-    // see https://github.com/facebook/docusaurus/issues/3567#issuecomment-706973805
+    /**
+     * If there's a broken link appearing very often, it is probably a broken link
+     * on the layout. Add an additional message in such case to help user figure
+     * this out. See https://github.com/facebook/docusaurus/issues/3567#issuecomment-706973805
+     */
     function getLayoutBrokenLinksHelpMessage() {
-        const flatList = lodash_1.flatten(Object.entries(allBrokenLinks).map(([pagePage, brokenLinks]) => brokenLinks.map((brokenLink) => ({ pagePage, brokenLink }))));
-        const countedBrokenLinks = lodash_1.countBy(flatList, (item) => item.brokenLink.link);
+        const flatList = Object.entries(allBrokenLinks).flatMap(([pagePage, brokenLinks]) => brokenLinks.map((brokenLink) => ({ pagePage, brokenLink })));
+        const countedBrokenLinks = lodash_1.default.countBy(flatList, (item) => item.brokenLink.link);
         const FrequencyThreshold = 5; // Is this a good value?
         const frequentLinks = Object.entries(countedBrokenLinks)
             .filter(([, count]) => count >= FrequencyThreshold)
@@ -83,51 +84,61 @@ function getBrokenLinksErrorMessage(allBrokenLinks) {
         if (frequentLinks.length === 0) {
             return '';
         }
-        return `\n\nIt looks like some of the broken links we found appear in many pages of your site.\nMaybe those broken links appear on all pages through your site layout?\nWe recommend that you check your theme configuration for such links (particularly, theme navbar and footer).\nFrequent broken links are linking to:\n- ${frequentLinks.join(`\n- `)}\n`;
+        return logger_1.default.interpolate `
+
+It looks like some of the broken links we found appear in many pages of your site.
+Maybe those broken links appear on all pages through your site layout?
+We recommend that you check your theme configuration for such links (particularly, theme navbar and footer).
+Frequent broken links are linking to:${frequentLinks}`;
     }
-    return (`Docusaurus found broken links!\n\nPlease check the pages of your site in the list below, and make sure you don't reference any path that does not exist.\nNote: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.${getLayoutBrokenLinksHelpMessage()}` +
-        `\n\nExhaustive list of all broken links found:\n${Object.entries(allBrokenLinks)
-            .map(([pagePath, brokenLinks]) => pageBrokenLinksMessage(pagePath, brokenLinks))
-            .join('\n')}
-`);
+    return `Docusaurus found broken links!
+
+Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
+Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.${getLayoutBrokenLinksHelpMessage()}
+
+Exhaustive list of all broken links found:
+${Object.entries(allBrokenLinks)
+        .map(([pagePath, brokenLinks]) => pageBrokenLinksMessage(pagePath, brokenLinks))
+        .join('\n')}
+`;
 }
-exports.getBrokenLinksErrorMessage = getBrokenLinksErrorMessage;
-function isExistingFile(filePath) {
+async function isExistingFile(filePath) {
     try {
-        return fs_extra_1.default.statSync(filePath).isFile();
+        return (await fs_extra_1.default.stat(filePath)).isFile();
     }
-    catch (e) {
+    catch {
         return false;
     }
 }
 // If a file actually exist on the file system, we know the link is valid
 // even if docusaurus does not know about this file, so we don't report it
 async function filterExistingFileLinks({ baseUrl, outDir, allCollectedLinks, }) {
-    // not easy to make this async :'(
-    function linkFileExists(link) {
+    async function linkFileExists(link) {
         // /baseUrl/javadoc/ -> /outDir/javadoc
-        const baseFilePath = utils_1.removeSuffix(`${outDir}/${utils_1.removePrefix(link, baseUrl)}`, '/');
+        const baseFilePath = onlyPathname((0, utils_1.removeSuffix)(`${outDir}/${(0, utils_1.removePrefix)(link, baseUrl)}`, '/'));
         // -> /outDir/javadoc
         // -> /outDir/javadoc.html
         // -> /outDir/javadoc/index.html
         const filePathsToTry = [baseFilePath];
         if (!path_1.default.extname(baseFilePath)) {
-            filePathsToTry.push(`${baseFilePath}.html`);
-            filePathsToTry.push(path_1.default.join(baseFilePath, 'index.html'));
+            filePathsToTry.push(`${baseFilePath}.html`, path_1.default.join(baseFilePath, 'index.html'));
         }
-        return filePathsToTry.some(isExistingFile);
+        for (const file of filePathsToTry) {
+            if (await isExistingFile(file)) {
+                return true;
+            }
+        }
+        return false;
     }
-    return lodash_1.mapValues(allCollectedLinks, (links) => {
-        return links.filter((link) => !linkFileExists(link));
-    });
+    return (0, combine_promises_1.default)(lodash_1.default.mapValues(allCollectedLinks, async (links) => (await Promise.all(links.map(async (link) => ((await linkFileExists(link)) ? '' : link)))).filter(Boolean)));
 }
-exports.filterExistingFileLinks = filterExistingFileLinks;
 async function handleBrokenLinks({ allCollectedLinks, onBrokenLinks, routes, baseUrl, outDir, }) {
     if (onBrokenLinks === 'ignore') {
         return;
     }
-    // If we link to a file like /myFile.zip, and the file actually exist for the file system
-    // it is not a broken link, it may simply be a link to an existing static file...
+    // If we link to a file like /myFile.zip, and the file actually exist for the
+    // file system. It is not a broken link, it may simply be a link to an
+    // existing static file...
     const allCollectedLinksFiltered = await filterExistingFileLinks({
         allCollectedLinks,
         baseUrl,
@@ -139,7 +150,7 @@ async function handleBrokenLinks({ allCollectedLinks, onBrokenLinks, routes, bas
     });
     const errorMessage = getBrokenLinksErrorMessage(allBrokenLinks);
     if (errorMessage) {
-        utils_1.reportMessage(errorMessage, onBrokenLinks);
+        (0, utils_1.reportMessage)(errorMessage, onBrokenLinks);
     }
 }
 exports.handleBrokenLinks = handleBrokenLinks;

package/lib/server/clientModules.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.
+ */
+import type { LoadedPlugin } from '@docusaurus/types';
+/**
+ * Runs the `getClientModules` lifecycle. The returned file paths are all
+ * absolute.
+ */
+export declare function loadClientModules(plugins: LoadedPlugin[]): string[];

package/lib/server/clientModules.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * 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.
+ */
+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)) ??
+        []);
+}
+exports.loadClientModules = loadClientModules;

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 { DocusaurusConfig } from '@docusaurus/types';
-export default function loadConfig(configPath: string): 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,15 +6,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+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");
-function loadConfig(configPath) {
-    if (!fs_extra_1.default.existsSync(configPath)) {
-        throw new Error(`Config file "${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 loadedConfig = import_fresh_1.default(configPath);
-    return configValidation_1.validateConfig(loadedConfig);
+    const importedConfig = (0, import_fresh_1.default)(siteConfigPath);
+    const loadedConfig = typeof importedConfig === 'function'
+        ? await importedConfig()
+        : await importedConfig;
+    const siteConfig = (0, configValidation_1.validateConfig)(loadedConfig);
+    return { siteConfig, siteConfigPath };
 }
-exports.default = loadConfig;
+exports.loadSiteConfig = loadSiteConfig;

package/lib/server/configValidation.d.ts

@@ -4,7 +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 { DocusaurusConfig, I18nConfig } from '@docusaurus/types';
+import type { DocusaurusConfig, I18nConfig } from '@docusaurus/types';
+import { Joi } from '@docusaurus/utils-validation';
 export declare const DEFAULT_I18N_CONFIG: I18nConfig;
-export declare const DEFAULT_CONFIG: Pick<DocusaurusConfig, 'i18n' | 'onBrokenLinks' | 'onBrokenMarkdownLinks' | 'onDuplicateRoutes' | 'plugins' | 'themes' | 'presets' | 'customFields' | 'themeConfig' | 'titleDelimiter' | 'noIndex' | 'baseUrlIssueBanner'>;
+export declare const DEFAULT_CONFIG: Pick<DocusaurusConfig, 'i18n' | 'onBrokenLinks' | 'onBrokenMarkdownLinks' | 'onDuplicateRoutes' | 'plugins' | 'themes' | 'presets' | 'stylesheets' | 'scripts' | 'clientModules' | 'customFields' | 'themeConfig' | 'titleDelimiter' | 'noIndex' | 'tagline' | 'baseUrlIssueBanner' | 'staticDirectories'>;
+export declare const ConfigSchema: Joi.ObjectSchema<any>;
 export declare function validateConfig(config: Partial<DocusaurusConfig>): DocusaurusConfig;

package/lib/server/configValidation.js

@@ -6,8 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateConfig = exports.DEFAULT_CONFIG = exports.DEFAULT_I18N_CONFIG = void 0;
-const constants_1 = require("../constants");
+exports.validateConfig = exports.ConfigSchema = exports.DEFAULT_CONFIG = exports.DEFAULT_I18N_CONFIG = void 0;
+const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const DEFAULT_I18N_LOCALE = 'en';
 exports.DEFAULT_I18N_CONFIG = {
@@ -23,23 +23,39 @@ exports.DEFAULT_CONFIG = {
     plugins: [],
     themes: [],
     presets: [],
+    stylesheets: [],
+    scripts: [],
+    clientModules: [],
     customFields: {},
     themeConfig: {},
     titleDelimiter: '|',
     noIndex: false,
+    tagline: '',
     baseUrlIssueBanner: true,
+    staticDirectories: [utils_1.DEFAULT_STATIC_DIR_NAME],
 };
-const PluginSchema = utils_validation_1.Joi.alternatives()
-    .try(utils_validation_1.Joi.function(), utils_validation_1.Joi.array().ordered(utils_validation_1.Joi.function().required(), utils_validation_1.Joi.object().required()), utils_validation_1.Joi.string(), utils_validation_1.Joi.array()
-    .ordered(utils_validation_1.Joi.string().required(), utils_validation_1.Joi.object().required())
-    .length(2), utils_validation_1.Joi.bool().equal(false))
-    // TODO isn't there a simpler way to customize the default Joi error message???
-    // Not sure why Joi makes it complicated to add a custom error message...
-    // See https://stackoverflow.com/a/54657686/82609
-    .error((errors) => {
-    errors.forEach((error) => {
-        error.message = ` => Bad Docusaurus plugin value as path [${error.path}].
-Example valid plugin config:
+function createPluginSchema(theme) {
+    return (utils_validation_1.Joi.alternatives()
+        .try(utils_validation_1.Joi.function(), utils_validation_1.Joi.array()
+        .ordered(utils_validation_1.Joi.function().required(), utils_validation_1.Joi.object().required())
+        .length(2), utils_validation_1.Joi.string(), utils_validation_1.Joi.array()
+        .ordered(utils_validation_1.Joi.string().required(), utils_validation_1.Joi.object().required())
+        .length(2), utils_validation_1.Joi.any().valid(false, null))
+        // @ts-expect-error: bad lib def, doesn't recognize an array of reports
+        .error((errors) => {
+        errors.forEach((error) => {
+            const validConfigExample = theme
+                ? `Example valid theme config:
+{
+  themes: [
+    ["@docusaurus/theme-classic",options],
+    "./myTheme",
+    ["./myTheme",{someOption: 42}],
+    function myTheme() { },
+    [function myTheme() { },options]
+  ],
+};`
+                : `Example valid plugin config:
 {
   plugins: [
     ["@docusaurus/plugin-content-docs",options],
@@ -48,16 +64,30 @@ Example valid plugin config:
     function myPlugin() { },
     [function myPlugin() { },options]
   ],
-};
+};`;
+            error.message = ` => Bad Docusaurus ${theme ? 'theme' : 'plugin'} value as path [${error.path}].
+${validConfigExample}
 `;
-    });
-    return errors;
+        });
+        return errors;
+    }));
+}
+const PluginSchema = createPluginSchema(false);
+const ThemeSchema = createPluginSchema(true);
+const PresetSchema = utils_validation_1.Joi.alternatives()
+    .try(utils_validation_1.Joi.string(), utils_validation_1.Joi.array()
+    .items(utils_validation_1.Joi.string().required(), utils_validation_1.Joi.object().required())
+    .length(2), utils_validation_1.Joi.any().valid(false, null))
+    .messages({
+    'alternatives.types': `{#label} does not look like a valid preset config. A preset config entry should be one of:
+- A tuple of [presetName, options], like \`["classic", \\{ blog: false \\}]\`, or
+- A simple string, like \`"classic"\``,
 });
-const ThemeSchema = utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.string(), utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().required(), utils_validation_1.Joi.object().required()).length(2));
-const PresetSchema = utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.string(), utils_validation_1.Joi.array().items(utils_validation_1.Joi.string().required(), utils_validation_1.Joi.object().required()).length(2));
 const LocaleConfigSchema = utils_validation_1.Joi.object({
     label: utils_validation_1.Joi.string(),
+    htmlLang: utils_validation_1.Joi.string(),
     direction: utils_validation_1.Joi.string().equal('ltr', 'rtl').default('ltr'),
+    calendar: utils_validation_1.Joi.string(),
 });
 const I18N_CONFIG_SCHEMA = utils_validation_1.Joi.object({
     defaultLocale: utils_validation_1.Joi.string().required(),
@@ -68,16 +98,29 @@ const I18N_CONFIG_SCHEMA = utils_validation_1.Joi.object({
 })
     .optional()
     .default(exports.DEFAULT_I18N_CONFIG);
+const SiteUrlSchema = utils_validation_1.URISchema.required().custom((value, helpers) => {
+    try {
+        const { pathname } = new URL(value);
+        if (pathname !== '/') {
+            helpers.warn('docusaurus.configValidationWarning', {
+                warningMessage: `the url is not supposed to contain a sub-path like '${pathname}', please use the baseUrl field for sub-paths`,
+            });
+        }
+    }
+    catch { }
+    return value;
+}, 'siteUrlCustomValidation');
 // TODO move to @docusaurus/utils-validation
-const ConfigSchema = utils_validation_1.Joi.object({
+exports.ConfigSchema = utils_validation_1.Joi.object({
     baseUrl: utils_validation_1.Joi.string()
         .required()
-        .regex(new RegExp('/$', 'm'))
-        .message('{{#label}} must be a string with a trailing `/`'),
+        .regex(/\/$/m)
+        .message('{{#label}} must be a string with a trailing slash.'),
     baseUrlIssueBanner: utils_validation_1.Joi.boolean().default(exports.DEFAULT_CONFIG.baseUrlIssueBanner),
-    favicon: utils_validation_1.Joi.string().required(),
+    favicon: utils_validation_1.Joi.string().optional(),
     title: utils_validation_1.Joi.string().required(),
-    url: utils_validation_1.URISchema.required(),
+    url: SiteUrlSchema,
+    trailingSlash: utils_validation_1.Joi.boolean(),
     i18n: I18N_CONFIG_SCHEMA,
     onBrokenLinks: utils_validation_1.Joi.string()
         .equal('ignore', 'log', 'warn', 'error', 'throw')
@@ -89,46 +132,60 @@ const ConfigSchema = utils_validation_1.Joi.object({
         .equal('ignore', 'log', 'warn', 'error', 'throw')
         .default(exports.DEFAULT_CONFIG.onDuplicateRoutes),
     organizationName: utils_validation_1.Joi.string().allow(''),
+    staticDirectories: utils_validation_1.Joi.array()
+        .items(utils_validation_1.Joi.string())
+        .default(exports.DEFAULT_CONFIG.staticDirectories),
     projectName: utils_validation_1.Joi.string().allow(''),
+    deploymentBranch: utils_validation_1.Joi.string().optional(),
     customFields: utils_validation_1.Joi.object().unknown().default(exports.DEFAULT_CONFIG.customFields),
     githubHost: utils_validation_1.Joi.string(),
     plugins: utils_validation_1.Joi.array().items(PluginSchema).default(exports.DEFAULT_CONFIG.plugins),
     themes: utils_validation_1.Joi.array().items(ThemeSchema).default(exports.DEFAULT_CONFIG.themes),
     presets: utils_validation_1.Joi.array().items(PresetSchema).default(exports.DEFAULT_CONFIG.presets),
     themeConfig: utils_validation_1.Joi.object().unknown().default(exports.DEFAULT_CONFIG.themeConfig),
-    scripts: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
+    scripts: utils_validation_1.Joi.array()
+        .items(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
         src: utils_validation_1.Joi.string().required(),
         async: utils_validation_1.Joi.bool(),
         defer: utils_validation_1.Joi.bool(),
     })
         // See https://github.com/facebook/docusaurus/issues/3378
-        .unknown()),
+        .unknown())
+        .messages({
+        'array.includes': '{#label} is invalid. A script must be a plain string (the src), or an object with at least a "src" property.',
+    })
+        .default(exports.DEFAULT_CONFIG.scripts),
     ssrTemplate: utils_validation_1.Joi.string(),
-    stylesheets: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
+    stylesheets: utils_validation_1.Joi.array()
+        .items(utils_validation_1.Joi.string(), utils_validation_1.Joi.object({
         href: utils_validation_1.Joi.string().required(),
-        type: utils_validation_1.Joi.string().required(),
-    }).unknown()),
-    clientModules: utils_validation_1.Joi.array().items(utils_validation_1.Joi.string()),
-    tagline: utils_validation_1.Joi.string().allow(''),
-    titleDelimiter: utils_validation_1.Joi.string().default('|'),
-    noIndex: utils_validation_1.Joi.bool().default(false),
+        type: utils_validation_1.Joi.string(),
+    }).unknown())
+        .messages({
+        'array.includes': '{#label} is invalid. A stylesheet must be a plain string (the href), or an object with at least a "href" property.',
+    })
+        .default(exports.DEFAULT_CONFIG.stylesheets),
+    clientModules: utils_validation_1.Joi.array()
+        .items(utils_validation_1.Joi.string())
+        .default(exports.DEFAULT_CONFIG.clientModules),
+    tagline: utils_validation_1.Joi.string().allow('').default(exports.DEFAULT_CONFIG.tagline),
+    titleDelimiter: utils_validation_1.Joi.string().default(exports.DEFAULT_CONFIG.titleDelimiter),
+    noIndex: utils_validation_1.Joi.bool().default(exports.DEFAULT_CONFIG.noIndex),
     webpack: utils_validation_1.Joi.object({
         jsLoader: utils_validation_1.Joi.alternatives()
             .try(utils_validation_1.Joi.string().equal('babel'), utils_validation_1.Joi.function())
             .optional(),
     }).optional(),
+}).messages({
+    'docusaurus.configValidationWarning': 'Docusaurus config validation warning. Field {#label}: {#warningMessage}',
 });
 // TODO move to @docusaurus/utils-validation
 function validateConfig(config) {
-    const { error, value } = ConfigSchema.validate(config, {
+    const { error, warning, value } = exports.ConfigSchema.validate(config, {
         abortEarly: false,
     });
+    (0, utils_validation_1.printWarning)(warning);
     if (error) {
-        utils_validation_1.logValidationBugReportHint();
-        if (utils_validation_1.isValidationDisabledEscapeHatch) {
-            console.error(error);
-            return config;
-        }
         const unknownFields = error.details.reduce((formattedError, err) => {
             if (err.type === 'object.unknown') {
                 return `${formattedError}"${err.path}",`;
@@ -139,7 +196,7 @@ function validateConfig(config) {
             ? `${accumulatedErr}${err.message}\n`
             : accumulatedErr, '');
         formattedError = unknownFields
-            ? `${formattedError}These field(s) [${unknownFields}] are not recognized in ${constants_1.DEFAULT_CONFIG_FILE_NAME}.\nIf you still want these fields to be in your configuration, put them in the 'customFields' attribute.\nSee https://docusaurus.io/docs/docusaurus.config.js/#customfields`
+            ? `${formattedError}These field(s) (${unknownFields}) are not recognized in ${utils_1.DEFAULT_CONFIG_FILE_NAME}.\nIf you still want these fields to be in your configuration, put them in the "customFields" field.\nSee https://docusaurus.io/docs/api/docusaurus-config/#customfields`
             : formattedError;
         throw new Error(formattedError);
     }

package/lib/server/getHostPort.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+export declare type HostPortOptions = {
+    host?: string;
+    port?: string;
+};
+export declare function getHostPort(options: HostPortOptions): Promise<{
+    host: string;
+    port: number | null;
+}>;

package/lib/server/getHostPort.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getHostPort = void 0;
+const tslib_1 = require("tslib");
+const child_process_1 = require("child_process");
+const detect_port_1 = tslib_1.__importDefault(require("detect-port"));
+const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
+const utils_1 = require("@docusaurus/utils");
+const prompts_1 = tslib_1.__importDefault(require("prompts"));
+const execOptions = {
+    encoding: 'utf8',
+    stdio: [/* stdin */ 'pipe', /* stdout */ 'pipe', /* stderr */ 'ignore'],
+};
+function clearConsole() {
+    process.stdout.write(process.platform === 'win32' ? '\x1B[2J\x1B[0f' : '\x1B[2J\x1B[3J\x1B[H');
+}
+function getProcessForPort(port) {
+    try {
+        const processId = (0, child_process_1.execSync)(`lsof -i:${port} -P -t -sTCP:LISTEN`, execOptions)
+            .split('\n')[0]
+            .trim();
+        const directory = (0, child_process_1.execSync)(`lsof -p ${processId} | awk '$4=="cwd" {for (i=9; i<=NF; i++) printf "%s ", $i}'`, execOptions).trim();
+        const command = (0, child_process_1.execSync)(`ps -o command -p ${processId} | sed -n 2p`, execOptions).replace(/\n$/, '');
+        return logger_1.default.interpolate `code=${command} subdue=${`(pid ${processId})`} in path=${directory}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 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 {
+        const port = await (0, detect_port_1.default)({ port: defaultPort, hostname: host });
+        if (port === defaultPort) {
+            return port;
+        }
+        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) {
+            logger_1.default.error(message);
+            return null;
+        }
+        clearConsole();
+        const existingProcess = getProcessForPort(defaultPort);
+        const { shouldChangePort } = await (0, prompts_1.default)({
+            type: 'confirm',
+            name: 'shouldChangePort',
+            message: logger_1.default.yellow(`${logger_1.default.bold('[WARNING]')} ${message}${existingProcess ? ` Probably:\n  ${existingProcess}` : ''}
+
+Would you like to run the app on another port instead?`),
+            initial: true,
+        });
+        return shouldChangePort ? port : null;
+    }
+    catch (err) {
+        logger_1.default.error `Could not find an open port at ${host}.`;
+        throw err;
+    }
+}
+async function getHostPort(options) {
+    const host = options.host ?? 'localhost';
+    const basePort = options.port ? parseInt(options.port, 10) : utils_1.DEFAULT_PORT;
+    const port = await choosePort(host, basePort);
+    return { host, port };
+}
+exports.getHostPort = getHostPort;

package/lib/server/htmlTags.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.
+ */
+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'>;