@docusaurus/core 3.9.1 → 3.9.2-alpha.0

package/README.md

@@ -1 +1,3 @@
-# Docusaurus core
+# `@docusaurus/core`
+
+The core package of Docusaurus

package/lib/client/exports/Link.js

@@ -63,7 +63,7 @@ function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLi
     const preloaded = useRef(false);
     const LinkComponent = (isNavLink ? NavLink : RRLink);
     const IOSupported = ExecutionEnvironment.canUseIntersectionObserver;
-    const ioRef = useRef();
+    const ioRef = useRef(undefined);
     const handleRef = (el) => {
         innerRef.current = el;
         if (IOSupported && el && isInternal) {

package/lib/client/exports/isInternalUrl.js

@@ -4,8 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+// Poor man's protocol detection
+// Spec: https://datatracker.ietf.org/doc/html/rfc3986#section-3.1
+// In particular: scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
 export function hasProtocol(url) {
-    return /^(?:\w*:|\/\/)/.test(url);
+    return /^(?:[A-Za-z][A-Za-z\d+.-]*:|\/\/)/.test(url);
 }
 export default function isInternalUrl(url) {
     return typeof url !== 'undefined' && !hasProtocol(url);

package/lib/commands/build/build.js

@@ -11,10 +11,9 @@ const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const logger_1 = tslib_1.__importStar(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
-const site_1 = require("../../server/site");
 const i18n_1 = require("../../server/i18n");
 const buildLocale_1 = require("./buildLocale");
-const buildUtils_1 = require("./buildUtils");
+const config_1 = require("../../server/config");
 async function build(siteDirParam = '.', cliOptions = {}) {
     process.env.BABEL_ENV = 'production';
     process.env.NODE_ENV = 'production';
@@ -50,24 +49,18 @@ function orderLocales({ locales, defaultLocale, }) {
     }
 }
 async function getLocalesToBuild({ siteDir, cliOptions, }) {
-    // TODO we shouldn't need to load all context + i18n just to get that list
-    // only loading siteConfig should be enough
-    const context = await (0, site_1.loadContext)({
+    const { siteConfig } = await (0, config_1.loadSiteConfig)({
         siteDir,
-        outDir: cliOptions.outDir,
-        config: cliOptions.config,
-        automaticBaseUrlLocalizationDisabled: (0, buildUtils_1.isAutomaticBaseUrlLocalizationDisabled)(cliOptions),
+        customConfigFilePath: cliOptions.config,
     });
-    const i18n = await (0, i18n_1.loadI18n)({
-        siteDir,
-        config: context.siteConfig,
-        currentLocale: context.siteConfig.i18n.defaultLocale, // Awkward but ok
-        automaticBaseUrlLocalizationDisabled: false,
-    });
-    const locales = cliOptions.locale ?? i18n.locales;
+    const locales = cliOptions.locale ??
+        (0, i18n_1.getLocaleList)({
+            i18nConfig: siteConfig.i18n,
+            currentLocale: siteConfig.i18n.defaultLocale, // Awkward but ok
+        });
     return orderLocales({
         locales: locales,
-        defaultLocale: i18n.defaultLocale,
+        defaultLocale: siteConfig.i18n.defaultLocale,
     });
 }
 async function tryToBuildLocale(params) {

package/lib/commands/build/buildLocale.js

@@ -22,6 +22,7 @@ const ssgExecutor_1 = require("../../ssg/ssgExecutor");
 const clearPath_1 = tslib_1.__importDefault(require("../utils/clearPath"));
 const buildUtils_1 = require("./buildUtils");
 const SkipBundling = process.env.DOCUSAURUS_SKIP_BUNDLING === 'true';
+const ReturnAfterLoading = process.env.DOCUSAURUS_RETURN_AFTER_LOADING === 'true';
 const ExitAfterLoading = process.env.DOCUSAURUS_EXIT_AFTER_LOADING === 'true';
 const ExitAfterBundling = process.env.DOCUSAURUS_EXIT_AFTER_BUNDLING === 'true';
 async function buildLocale({ siteDir, locale, cliOptions, }) {
@@ -37,6 +38,9 @@ async function buildLocale({ siteDir, locale, cliOptions, }) {
         locale,
         automaticBaseUrlLocalizationDisabled: (0, buildUtils_1.isAutomaticBaseUrlLocalizationDisabled)(cliOptions),
     }));
+    if (ReturnAfterLoading) {
+        return;
+    }
     if (ExitAfterLoading) {
         return process.exit(0);
     }
@@ -128,7 +132,7 @@ async function getBuildClientConfig({ props, cliOptions, configureWebpackUtils,
     const result = await (0, client_1.createBuildClientConfig)({
         props,
         minify: cliOptions.minify ?? true,
-        faster: props.siteConfig.future.experimental_faster,
+        faster: props.siteConfig.future.faster,
         configureWebpackUtils,
         bundleAnalyzer: cliOptions.bundleAnalyzer ?? false,
     });

package/lib/commands/cli.js

@@ -135,8 +135,10 @@ async function createCLIProgram({ cli, cliArgs, siteDir, config, }) {
     cli
         .command('write-heading-ids [siteDir] [files...]')
         .description('Generate heading ids in Markdown content.')
+        .option('--syntax <syntax>', 'heading ID syntax: "classic" ({#id}) or "mdx-comment" ({/* #id */}) (default: "classic")')
+        .option('--migrate', 'migrate existing heading IDs to the target --syntax, if they are using a different syntax (default: false)')
+        .option('--overwrite', 'overwrite existing heading IDs, re-generate them from the heading text (default: false)')
         .option('--maintain-case', "keep the headings' casing, otherwise make all lowercase (default: false)")
-        .option('--overwrite', 'overwrite existing heading IDs (default: false)')
         .action(writeHeadingIds_1.writeHeadingIds);
     cli.arguments('<command>').action((cmd) => {
         cli.outputHelp();

package/lib/commands/start/webpack.js

@@ -102,7 +102,7 @@ async function getStartClientConfig({ props, minify, poll, configureWebpackUtils
     let { clientConfig: config } = await (0, client_1.createStartClientConfig)({
         props,
         minify,
-        faster: props.siteConfig.future.experimental_faster,
+        faster: props.siteConfig.future.faster,
         poll,
         configureWebpackUtils,
     });

package/lib/commands/swizzle/index.js

@@ -10,7 +10,6 @@ exports.swizzle = swizzle;
 const tslib_1 = require("tslib");
 const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
-const utils_1 = require("@docusaurus/utils");
 const themes_1 = require("./themes");
 const components_1 = require("./components");
 const tables_1 = require("./tables");
@@ -33,7 +32,7 @@ async function getLanguageForThemeName({ themeName, plugins, options, }) {
     }
     // It's only useful to prompt the user for themes that support both JS/TS
     if (supportsTS) {
-        return (0, utils_1.askPreferredLanguage)({ exit: true });
+        return (0, prompts_1.askSwizzlePreferredLanguage)();
     }
     return 'javascript';
 }

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

@@ -10,3 +10,4 @@ export declare function askThemeName(themeNames: string[]): Promise<string>;
 export declare function askComponentName(themeComponents: ThemeComponents): Promise<string>;
 export declare function askSwizzleDangerousComponent(): Promise<boolean>;
 export declare function askSwizzleAction(componentConfig: SwizzleComponentConfig): Promise<SwizzleAction>;
+export declare function askSwizzlePreferredLanguage(): Promise<'javascript' | 'typescript'>;

package/lib/commands/swizzle/prompts.js

@@ -10,6 +10,7 @@ exports.askThemeName = askThemeName;
 exports.askComponentName = askComponentName;
 exports.askSwizzleDangerousComponent = askSwizzleDangerousComponent;
 exports.askSwizzleAction = askSwizzleAction;
+exports.askSwizzlePreferredLanguage = askSwizzlePreferredLanguage;
 const tslib_1 = require("tslib");
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const prompts_1 = tslib_1.__importDefault(require("prompts"));
@@ -107,3 +108,24 @@ async function askSwizzleAction(componentConfig) {
     }
     return action;
 }
+async function askSwizzlePreferredLanguage() {
+    const choices = [
+        { title: logger_1.default.bold('JavaScript'), value: 'javascript' },
+        { title: logger_1.default.bold('TypeScript'), value: 'typescript' },
+        { title: logger_1.default.yellow('[Exit]'), value: '[Exit]' },
+    ];
+    const { language } = await (0, prompts_1.default)({
+        type: 'select',
+        name: 'language',
+        message: 'Which language do you want to use?',
+        choices,
+    }, {
+        onCancel() {
+            process.exit(0);
+        },
+    });
+    if (typeof language === 'undefined' || language === '[Exit]') {
+        process.exit(0);
+    }
+    return language;
+}

package/lib/commands/utils/openBrowser/openBrowser.js

@@ -69,6 +69,9 @@ async function tryOpenWithAppleScript({ url, browser, }) {
             // We open Google Chrome Canary in priority over Google Chrome
             return supportedChromiumBrowsers.filter((b) => activeBrowsers.includes(b));
         }
+        // Test this manually with:
+        // osascript ./packages/docusaurus/src/commands/utils/openBrowser/openChrome.applescript "http://localhost:8080" "Google Chrome"
+        // osascript ./packages/docusaurus/src/commands/utils/openBrowser/openChrome.applescript "http://localhost:8080" "Arc"
         async function tryBrowser(browserName) {
             try {
                 // This command runs the openChrome.applescript (copied from CRA)

package/lib/commands/utils/openBrowser/openChrome.applescript

@@ -19,6 +19,16 @@ on run argv
     set theProgram to item 2 of argv
   end if
 
+  -- Arc: simple open + activate, no tab reuse
+  -- See https://github.com/facebook/docusaurus/issues/11582
+  if theProgram is "Arc" then
+    tell application "Arc"
+      activate
+      open location theURL
+    end tell
+    return
+  end if
+
   using terms from application "Google Chrome"
     tell application theProgram
 

package/lib/commands/writeHeadingIds.js

@@ -13,9 +13,25 @@ const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const utils_1 = require("@docusaurus/utils");
 const site_1 = require("../server/site");
 const init_1 = require("../server/plugins/init");
+function inferFallbackSyntax(_filepath) {
+    // TODO Docusaurus v4 - infer the syntax based on the file extensions?
+    // This is not ideal because we have many ways to define the syntax
+    // (front matter "format", siteConfig.markdown.format etc...)
+    // but probably good enough for now
+    // Until then, we default to the classic syntax
+    // The mdx-comment syntax is opt-in
+    return 'classic';
+}
+function getHeadingIdSyntax(filepath, options) {
+    return options?.syntax ?? inferFallbackSyntax(filepath);
+}
 async function transformMarkdownFile(filepath, options) {
     const content = await fs_extra_1.default.readFile(filepath, 'utf8');
-    const updatedContent = (0, utils_1.writeMarkdownHeadingId)(content, options);
+    const syntax = getHeadingIdSyntax(filepath, options);
+    const updatedContent = (0, utils_1.writeMarkdownHeadingId)(content, {
+        ...options,
+        syntax,
+    });
     if (content !== updatedContent) {
         await fs_extra_1.default.writeFile(filepath, updatedContent);
         return filepath;
@@ -33,17 +49,35 @@ async function getPathsToWatch(siteDir) {
     const plugins = await (0, init_1.initPlugins)(context);
     return plugins.flatMap((plugin) => plugin.getPathsToWatch?.() ?? []);
 }
+// TODO Docusaurus v4 - Upgrade commander, use choices() API?
+function validateOptions(options) {
+    const validSyntaxValues = ['classic', 'mdx-comment'];
+    if (options.syntax && !validSyntaxValues.includes(options.syntax)) {
+        throw new Error(`Invalid --syntax value "${options.syntax}". Valid values: ${validSyntaxValues.join(', ')}`);
+    }
+    if (options.overwrite && options.migrate) {
+        throw new Error("Options --overwrite and --migrate cannot be used together.\nThe --overwrite already re-generates IDs in the target syntax, so the --migrate option wouldn't have any effect.");
+    }
+}
 async function writeHeadingIds(siteDirParam = '.', files = [], options = {}) {
+    validateOptions(options);
     const siteDir = await fs_extra_1.default.realpath(siteDirParam);
-    const markdownFiles = await (0, utils_1.safeGlobby)(files ?? (await getPathsToWatch(siteDir)), {
+    const patterns = files.length ? files : await getPathsToWatch(siteDir);
+    const markdownFiles = await (0, utils_1.safeGlobby)(patterns, {
         expandDirectories: ['**/*.{md,mdx}'],
     });
+    if (markdownFiles.length === 0) {
+        logger_1.default.warn `No markdown files found in siteDir path=${siteDir} for patterns: ${patterns}`;
+        return;
+    }
     const result = await Promise.all(markdownFiles.map((p) => transformMarkdownFile(p, options)));
     const pathsModified = result.filter(Boolean);
     if (pathsModified.length) {
         logger_1.default.success `Heading ids added to Markdown files (number=${`${pathsModified.length}/${markdownFiles.length}`} files): ${pathsModified}`;
     }
     else {
-        logger_1.default.warn `number=${markdownFiles.length} Markdown files already have explicit heading IDs. If you intend to overwrite the existing heading IDs, use the code=${'--overwrite'} option.`;
+        logger_1.default.warn `number=${markdownFiles.length} Markdown files already have explicit heading IDs.
+If you intend to overwrite the existing heading IDs, use the code=${'--overwrite'} option.
+If you intend to change their heading ID syntax, use the code=${'--migrate'} option.`;
     }
 }

package/lib/server/configValidation.d.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Joi } from '@docusaurus/utils-validation';
-import type { FasterConfig, FutureConfig, FutureV4Config, StorageConfig, DocusaurusConfig, I18nConfig, MarkdownConfig, MarkdownHooks } from '@docusaurus/types';
+import type { DocusaurusConfig, FasterConfig, FutureConfig, FutureV4Config, I18nConfig, MarkdownConfig, MarkdownHooks, StorageConfig } from '@docusaurus/types';
 export declare const DEFAULT_I18N_CONFIG: I18nConfig;
 export declare const DEFAULT_STORAGE_CONFIG: StorageConfig;
 export declare const DEFAULT_FASTER_CONFIG: FasterConfig;
@@ -15,6 +15,6 @@ export declare const DEFAULT_FUTURE_V4_CONFIG_TRUE: FutureV4Config;
 export declare const DEFAULT_FUTURE_CONFIG: FutureConfig;
 export declare const DEFAULT_MARKDOWN_HOOKS: MarkdownHooks;
 export declare const DEFAULT_MARKDOWN_CONFIG: MarkdownConfig;
-export declare const DEFAULT_CONFIG: Pick<DocusaurusConfig, 'i18n' | 'future' | 'onBrokenLinks' | 'onBrokenAnchors' | 'onBrokenMarkdownLinks' | 'onDuplicateRoutes' | 'plugins' | 'themes' | 'presets' | 'headTags' | 'stylesheets' | 'scripts' | 'clientModules' | 'customFields' | 'themeConfig' | 'titleDelimiter' | 'noIndex' | 'tagline' | 'baseUrlIssueBanner' | 'staticDirectories' | 'markdown'>;
+export declare const DEFAULT_CONFIG: Pick<DocusaurusConfig, 'i18n' | 'storage' | 'future' | 'onBrokenLinks' | 'onBrokenAnchors' | 'onBrokenMarkdownLinks' | 'onDuplicateRoutes' | 'plugins' | 'themes' | 'presets' | 'headTags' | 'stylesheets' | 'scripts' | 'clientModules' | 'customFields' | 'themeConfig' | 'titleDelimiter' | 'noIndex' | 'tagline' | 'baseUrlIssueBanner' | 'staticDirectories' | 'markdown'>;
 export declare const ConfigSchema: Joi.ObjectSchema<DocusaurusConfig>;
 export declare function validateConfig(config: unknown, siteConfigPath: string): DocusaurusConfig;

package/lib/server/configValidation.js

@@ -55,6 +55,7 @@ exports.DEFAULT_FASTER_CONFIG = {
     rspackBundler: false,
     rspackPersistentCache: false,
     ssgWorkerThreads: false,
+    gitEagerVcs: false,
 };
 // When using the "faster: true" shortcut
 exports.DEFAULT_FASTER_CONFIG_TRUE = {
@@ -66,20 +67,25 @@ exports.DEFAULT_FASTER_CONFIG_TRUE = {
     rspackBundler: true,
     rspackPersistentCache: true,
     ssgWorkerThreads: true,
+    gitEagerVcs: true,
 };
 exports.DEFAULT_FUTURE_V4_CONFIG = {
     removeLegacyPostBuildHeadAttribute: false,
     useCssCascadeLayers: false,
+    siteStorageNamespacing: false,
+    fasterByDefault: false,
 };
 // When using the "v4: true" shortcut
 exports.DEFAULT_FUTURE_V4_CONFIG_TRUE = {
     removeLegacyPostBuildHeadAttribute: true,
     useCssCascadeLayers: true,
+    siteStorageNamespacing: true,
+    fasterByDefault: true,
 };
 exports.DEFAULT_FUTURE_CONFIG = {
     v4: exports.DEFAULT_FUTURE_V4_CONFIG,
-    experimental_faster: exports.DEFAULT_FASTER_CONFIG,
-    experimental_storage: exports.DEFAULT_STORAGE_CONFIG,
+    faster: exports.DEFAULT_FASTER_CONFIG,
+    experimental_vcs: (0, utils_1.getVcsPreset)('default-v1'),
     experimental_router: 'browser',
 };
 exports.DEFAULT_MARKDOWN_HOOKS = {
@@ -105,6 +111,7 @@ exports.DEFAULT_MARKDOWN_CONFIG = {
 };
 exports.DEFAULT_CONFIG = {
     i18n: exports.DEFAULT_I18N_CONFIG,
+    storage: exports.DEFAULT_STORAGE_CONFIG,
     future: exports.DEFAULT_FUTURE_CONFIG,
     onBrokenLinks: 'throw',
     onBrokenAnchors: 'warn', // TODO Docusaurus v4: change to throw
@@ -180,6 +187,7 @@ const LocaleConfigSchema = utils_validation_1.Joi.object({
     direction: utils_validation_1.Joi.string().equal('ltr', 'rtl'),
     calendar: utils_validation_1.Joi.string(),
     path: utils_validation_1.Joi.string(),
+    translate: utils_validation_1.Joi.boolean(),
     url: SiteUrlSchema,
     baseUrl: BaseUrlSchema,
 });
@@ -193,25 +201,30 @@ const I18N_CONFIG_SCHEMA = utils_validation_1.Joi.object({
 })
     .optional()
     .default(exports.DEFAULT_I18N_CONFIG);
+// Individual boolean defaults are not set here on purpose
+// They are resolved in postProcessDocusaurusConfig based on
+// the future.v4.fasterByDefault flag
 const FASTER_CONFIG_SCHEMA = utils_validation_1.Joi.alternatives()
     .try(utils_validation_1.Joi.object({
-    swcJsLoader: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.swcJsLoader),
-    swcJsMinimizer: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.swcJsMinimizer),
-    swcHtmlMinimizer: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.swcHtmlMinimizer),
-    lightningCssMinimizer: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.lightningCssMinimizer),
-    mdxCrossCompilerCache: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.mdxCrossCompilerCache),
-    rspackBundler: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.rspackBundler),
-    rspackPersistentCache: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.rspackPersistentCache),
-    ssgWorkerThreads: utils_validation_1.Joi.boolean().default(exports.DEFAULT_FASTER_CONFIG.ssgWorkerThreads),
+    swcJsLoader: utils_validation_1.Joi.boolean(),
+    swcJsMinimizer: utils_validation_1.Joi.boolean(),
+    swcHtmlMinimizer: utils_validation_1.Joi.boolean(),
+    lightningCssMinimizer: utils_validation_1.Joi.boolean(),
+    mdxCrossCompilerCache: utils_validation_1.Joi.boolean(),
+    rspackBundler: utils_validation_1.Joi.boolean(),
+    rspackPersistentCache: utils_validation_1.Joi.boolean(),
+    ssgWorkerThreads: utils_validation_1.Joi.boolean(),
+    gitEagerVcs: utils_validation_1.Joi.boolean(),
 }), utils_validation_1.Joi.boolean()
     .required()
     .custom((bool) => bool ? exports.DEFAULT_FASTER_CONFIG_TRUE : exports.DEFAULT_FASTER_CONFIG))
-    .optional()
-    .default(exports.DEFAULT_FASTER_CONFIG);
+    .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),
 }), utils_validation_1.Joi.boolean()
     .required()
     .custom((bool) => bool ? exports.DEFAULT_FUTURE_V4_CONFIG_TRUE : exports.DEFAULT_FUTURE_V4_CONFIG))
@@ -221,19 +234,58 @@ const STORAGE_CONFIG_SCHEMA = utils_validation_1.Joi.object({
     type: utils_validation_1.Joi.string()
         .equal('localStorage', 'sessionStorage')
         .default(exports.DEFAULT_STORAGE_CONFIG.type),
-    namespace: utils_validation_1.Joi.alternatives()
-        .try(utils_validation_1.Joi.string(), utils_validation_1.Joi.boolean())
-        .default(exports.DEFAULT_STORAGE_CONFIG.namespace),
+    // namespace default is not set here on purpose
+    // It is resolved in postProcessDocusaurusConfig based on
+    // the future.v4.siteStorageNamespacing flag
+    namespace: utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.string(), utils_validation_1.Joi.boolean()),
 })
     .optional()
-    .default(exports.DEFAULT_STORAGE_CONFIG);
+    .default({ type: exports.DEFAULT_STORAGE_CONFIG.type });
+const VCS_CONFIG_OBJECT_SCHEMA = utils_validation_1.Joi.object({
+    // All the fields are required on purpose
+    // You either provide a full VCS config or nothing
+    initialize: utils_validation_1.Joi.function().maxArity(1).required(),
+    getFileCreationInfo: utils_validation_1.Joi.function().arity(1).required(),
+    getFileLastUpdateInfo: utils_validation_1.Joi.function().arity(1).required(),
+});
+const VCS_CONFIG_SCHEMA = utils_validation_1.Joi.custom((input) => {
+    if (typeof input === 'string') {
+        const presetName = input;
+        if (!utils_1.VcsPresetNames.includes(presetName)) {
+            throw new Error(`VCS config preset name '${input}' is not valid.`);
+        }
+        return (0, utils_1.getVcsPreset)(presetName);
+    }
+    if (typeof input === 'boolean') {
+        // We return the boolean on purpose
+        // We'll normalize it to a real VcsConfig later
+        // This is annoying, but we have to read the future flag to switch to the
+        // new "default-v2" config (not easy to do it here)
+        return input;
+    }
+    const { error, value } = VCS_CONFIG_OBJECT_SCHEMA.validate(input);
+    if (error) {
+        throw error;
+    }
+    return value;
+}).default(true);
 const FUTURE_CONFIG_SCHEMA = utils_validation_1.Joi.object({
     v4: FUTURE_V4_SCHEMA,
-    experimental_faster: FASTER_CONFIG_SCHEMA,
-    experimental_storage: STORAGE_CONFIG_SCHEMA,
+    faster: FASTER_CONFIG_SCHEMA,
+    experimental_vcs: VCS_CONFIG_SCHEMA,
     experimental_router: utils_validation_1.Joi.string()
         .equal('browser', 'hash')
         .default(exports.DEFAULT_FUTURE_CONFIG.experimental_router),
+    experimental_storage: utils_validation_1.Joi.any()
+        .forbidden()
+        .messages({
+        'any.unknown': `The Docusaurus config ${logger_1.default.code('future.experimental_storage')} has been promoted to a stable top-level ${logger_1.default.code('storage')} config attribute. Please move your storage config to the top level.`,
+    }),
+    experimental_faster: utils_validation_1.Joi.any()
+        .forbidden()
+        .messages({
+        'any.unknown': `The Docusaurus config ${logger_1.default.code('future.experimental_faster')} has been renamed to ${logger_1.default.code('future.faster')}. Please update your Docusaurus config.`,
+    }),
 })
     .optional()
     .default(exports.DEFAULT_FUTURE_CONFIG);
@@ -246,6 +298,7 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
     title: utils_validation_1.Joi.string().required(),
     trailingSlash: utils_validation_1.Joi.boolean(), // No default value! undefined = retrocompatible legacy behavior!
     i18n: I18N_CONFIG_SCHEMA,
+    storage: STORAGE_CONFIG_SCHEMA,
     future: FUTURE_CONFIG_SCHEMA,
     onBrokenLinks: utils_validation_1.Joi.string()
         .equal('ignore', 'log', 'warn', 'throw')
@@ -288,9 +341,14 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
     headTags: utils_validation_1.Joi.array()
         .items(utils_validation_1.Joi.object({
         tagName: utils_validation_1.Joi.string().required(),
-        attributes: utils_validation_1.Joi.object()
-            .pattern(/[\w-]+/, utils_validation_1.Joi.string())
-            .required(),
+        attributes: utils_validation_1.Joi.object().when('customElement', {
+            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())
+                .required(),
+        }),
+        customElement: utils_validation_1.Joi.bool().default(false),
     }).unknown())
         .messages({
         'array.includes': '{#label} is invalid. A headTag must be an object with at least a "tagName" and an "attributes" property.',
@@ -355,6 +413,41 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
 // Expressing this kind of logic in Joi is a pain
 // We also want to decouple logic from Joi: easier to remove it later!
 function postProcessDocusaurusConfig(config) {
+    // Resolve storage.namespace based on the v4 future flag
+    // undefined means "not explicitly set by user"
+    if (config.storage.namespace === undefined) {
+        config.storage.namespace = config.future.v4.siteStorageNamespacing;
+    }
+    // Resolve faster config based on the v4.fasterByDefault flag
+    // undefined means "not explicitly set by user"
+    if (config.future.faster === undefined) {
+        config.future.faster = {};
+    }
+    const fasterDefault = config.future.v4.fasterByDefault;
+    const fasterKeys = Object.keys(exports.DEFAULT_FASTER_CONFIG);
+    for (const key of fasterKeys) {
+        if (config.future.faster[key] === undefined) {
+            config.future.faster[key] = fasterDefault;
+        }
+    }
+    // Docusaurus Faster doesn't fully support Yarn PnP :s
+    // Until we support Rspack + PnP, we simply revert to Webpack with a warning
+    // See https://github.com/facebook/docusaurus/issues/10787
+    if (process.versions.pnp) {
+        if (config.future.faster.rspackBundler) {
+            logger_1.default.warn(`Docusaurus Faster doesn't fully support the Yarn PnP linker yet.
+We recommend to use Yarn node-linker instead.
+Docusaurus will still attempt to build your app with Webpack (instead of Rspack) and use slower minimizers.
+See also https://github.com/facebook/docusaurus/issues/10787`);
+            config.future.faster.rspackBundler = false;
+            config.future.faster.rspackPersistentCache = false;
+            // This also won't work due to Webpack libs using peerDependencies :s
+            // This could eventually work if the deps are added at the site level
+            // TODO Docusaurus v4 clean this up
+            config.future.faster.lightningCssMinimizer = false;
+            config.future.faster.swcJsMinimizer = false;
+        }
+    }
     if (config.onBrokenMarkdownLinks) {
         logger_1.default.warn `The code=${'siteConfig.onBrokenMarkdownLinks'} config option is deprecated and will be removed in Docusaurus v4.
 Please migrate and move this option to code=${'siteConfig.markdown.hooks.onBrokenMarkdownLinks'} instead.`;
@@ -363,15 +456,24 @@ Please migrate and move this option to code=${'siteConfig.markdown.hooks.onBroke
         // We erase the former one to ensure we don't use it anywhere
         config.onBrokenMarkdownLinks = undefined;
     }
-    if (config.future.experimental_faster.ssgWorkerThreads &&
+    // We normalize the VCS config when using a boolean value
+    if (typeof config.future.experimental_vcs === 'boolean') {
+        const vcsConfig = config.future.experimental_vcs
+            ? config.future.faster.gitEagerVcs
+                ? (0, utils_1.getVcsPreset)('default-v2')
+                : (0, utils_1.getVcsPreset)('default-v1')
+            : (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.experimental_faster.ssgWorkerThreads')} requires the future flag ${logger_1.default.code('future.v4.removeLegacyPostBuildHeadAttribute')} to be turned on.
+        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.experimental_faster.rspackPersistentCache &&
-        !config.future.experimental_faster.rspackBundler) {
-        throw new Error(`Docusaurus config flag ${logger_1.default.code('future.experimental_faster.rspackPersistentCache')} requires the flag ${logger_1.default.code('future.experimental_faster.rspackBundler')} to be turned on.`);
+    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.`);
     }
 }
 // TODO move to @docusaurus/utils-validation

package/lib/server/htmlTags.js

@@ -12,15 +12,18 @@ 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 escape_html_1 = tslib_1.__importDefault(require("escape-html"));
+// TODO this should be done at config validation time, not here
 function assertIsHtmlTagObject(val) {
     if (typeof val !== 'object' || !val) {
         throw new Error(`"${val}" is not a valid HTML tag object.`);
     }
-    if (typeof val.tagName !== 'string') {
+    const htmlTag = val;
+    if (typeof htmlTag.tagName !== 'string') {
         throw new Error(`${JSON.stringify(val)} is not a valid HTML tag object. "tagName" must be defined as a string.`);
     }
-    if (!html_tags_1.default.includes(val.tagName)) {
-        throw new Error(`Error loading ${JSON.stringify(val)}, "${val.tagName}" is not a valid HTML tag.`);
+    if (!htmlTag.customElement &&
+        !html_tags_1.default.includes(htmlTag.tagName)) {
+        throw new Error(`Error loading ${JSON.stringify(val)}, "${htmlTag.tagName}" is not a valid HTML tag. Either use a valid "tagName" or set "customElement: true".`);
     }
 }
 function hashRouterAbsoluteToRelativeTagAttribute(name, value) {

package/lib/server/i18n.d.ts

@@ -4,8 +4,12 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { I18n, DocusaurusConfig, I18nLocaleConfig } from '@docusaurus/types';
+import type { I18n, DocusaurusConfig, I18nLocaleConfig, I18nConfig } from '@docusaurus/types';
 export declare function getDefaultLocaleConfig(locale: string): Omit<I18nLocaleConfig, 'translate' | 'url' | 'baseUrl'>;
+export declare function getLocaleList({ i18nConfig, currentLocale, }: {
+    i18nConfig: I18nConfig;
+    currentLocale: string;
+}): [string, ...string[]];
 export declare function loadI18n({ siteDir, config, currentLocale, automaticBaseUrlLocalizationDisabled, }: {
     siteDir: string;
     config: DocusaurusConfig;

package/lib/server/i18n.js

@@ -7,6 +7,7 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getDefaultLocaleConfig = getDefaultLocaleConfig;
+exports.getLocaleList = getLocaleList;
 exports.loadI18n = loadI18n;
 const tslib_1 = require("tslib");
 const path_1 = tslib_1.__importDefault(require("path"));
@@ -82,22 +83,29 @@ function getDefaultLocaleConfig(locale) {
         };
     }
     catch (e) {
-        throw new Error(`Docusaurus couldn't get default locale config for ${locale}`, { cause: e });
+        throw new Error(`Docusaurus couldn't infer a default locale config for ${logger_1.default.name(locale)}.
+Make sure it is a valid BCP 47 locale name (e.g. en, fr, fr-FR, etc.) and/or provide a valid BCP 47 ${logger_1.default.code(`siteConfig.i18n.localeConfig['${locale}'].htmlLang`)} attribute.`, { cause: e });
     }
 }
-async function loadI18n({ siteDir, config, currentLocale, automaticBaseUrlLocalizationDisabled, }) {
-    const { i18n: i18nConfig } = config;
+function getLocaleList({ i18nConfig, currentLocale, }) {
     if (!i18nConfig.locales.includes(currentLocale)) {
-        logger_1.default.warn `The locale name=${currentLocale} was not found in your site configuration: Available locales are: ${i18nConfig.locales}
-Note: Docusaurus only support running one locale at a time.`;
+        logger_1.default.warn `The locale name=${currentLocale} was not found in your Docusaurus site configuration.
+We recommend adding the name=${currentLocale} to your site i18n config, but we will still try to run your site.
+Declared site config locales are: ${i18nConfig.locales}`;
+        return i18nConfig.locales.concat(currentLocale);
     }
-    const locales = i18nConfig.locales.includes(currentLocale)
-        ? i18nConfig.locales
-        : i18nConfig.locales.concat(currentLocale);
+    return i18nConfig.locales;
+}
+async function loadI18n({ siteDir, config, currentLocale, automaticBaseUrlLocalizationDisabled, }) {
+    const { i18n: i18nConfig } = config;
+    const locales = getLocaleList({
+        i18nConfig,
+        currentLocale,
+    });
     async function getFullLocaleConfig(locale) {
         const localeConfigInput = i18nConfig.localeConfigs[locale] ?? {};
         const localeConfig = {
-            ...getDefaultLocaleConfig(locale),
+            ...getDefaultLocaleConfig(localeConfigInput.htmlLang ?? locale),
             ...localeConfigInput,
         };
         // By default, translations will be enabled if i18n/<locale> dir exists

package/lib/server/plugins/synthetic.js

@@ -60,7 +60,7 @@ function createBootstrapPlugin({ siteDir, siteConfig, }) {
  */
 async function createMDXFallbackPlugin({ siteDir, siteConfig, }) {
     const mdxLoaderItem = await (0, mdx_loader_1.createMDXLoaderItem)({
-        useCrossCompilerCache: siteConfig.future.experimental_faster.mdxCrossCompilerCache,
+        useCrossCompilerCache: siteConfig.future.faster.mdxCrossCompilerCache,
         admonitions: true,
         staticDirs: siteConfig.staticDirectories.map((dir) => path_1.default.resolve(siteDir, dir)),
         siteDir,

package/lib/server/site.js

@@ -43,6 +43,14 @@ async function loadContext(params) {
             customConfigFilePath,
         }),
     });
+    // Not sure where is the best place to put this VCS initialization call?
+    // The sooner is probably the better
+    // Note: we don't await the result on purpose!
+    // VCS initialization can be slow for large repos, and we don't want to block
+    // VCS integrations should be carefully designed to avoid blocking
+    logger_1.PerfLogger.async('VCS init', () => {
+        return initialSiteConfig.future.experimental_vcs.initialize({ siteDir });
+    });
     const currentBundler = await (0, bundler_1.getCurrentBundler)({
         siteConfig: initialSiteConfig,
     });

package/lib/server/siteMessages.js

@@ -15,7 +15,7 @@ const babel_1 = require("@docusaurus/babel");
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
 const uselessBabelConfigMessages = async ({ site }) => {
     const { props: { siteDir, siteConfig }, } = site;
-    if (siteConfig.future.experimental_faster.swcJsLoader) {
+    if (siteConfig.future.faster.swcJsLoader) {
         const babelConfigFilePath = await (0, babel_1.getCustomBabelConfigFilePath)(siteDir);
         if (babelConfigFilePath) {
             return [

package/lib/server/storage.d.ts

@@ -5,9 +5,6 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { DocusaurusConfig, SiteStorage } from '@docusaurus/types';
-type PartialFuture = Pick<DocusaurusConfig['future'], 'experimental_storage'>;
-type PartialConfig = Pick<DocusaurusConfig, 'url' | 'baseUrl'> & {
-    future: PartialFuture;
-};
+type PartialConfig = Pick<DocusaurusConfig, 'url' | 'baseUrl' | 'storage'>;
 export declare function createSiteStorage(config: PartialConfig): SiteStorage;
 export {};

package/lib/server/storage.js

@@ -14,18 +14,18 @@ function automaticNamespace(config) {
     return (0, utils_1.simpleHash)(normalizedUrl, 3);
 }
 function getNamespaceString(config) {
-    if (config.future.experimental_storage.namespace === true) {
+    if (config.storage.namespace === true) {
         return automaticNamespace(config);
     }
-    else if (config.future.experimental_storage.namespace === false) {
+    else if (config.storage.namespace === false) {
         return null;
     }
     else {
-        return config.future.experimental_storage.namespace;
+        return config.storage.namespace;
     }
 }
 function createSiteStorage(config) {
-    const { type } = config.future.experimental_storage;
+    const { type } = config.storage;
     const namespaceString = getNamespaceString(config);
     const namespace = namespaceString ? `-${namespaceString}` : '';
     return {

package/lib/ssg/ssgExecutor.js

@@ -136,8 +136,7 @@ async function executeSSG({ props, serverBundlePath, clientManifestPath, router,
         logger_1.PerfLogger.end('Generate Hash Router entry point');
         return { collectedData: {} };
     }
-    const createExecutor = props.siteConfig.future.experimental_faster
-        .ssgWorkerThreads
+    const createExecutor = props.siteConfig.future.faster.ssgWorkerThreads
         ? createPooledSSGExecutor
         : createSimpleSSGExecutor;
     const executor = await createExecutor({ params, pathnames: props.routesPaths });

package/lib/ssg/ssgParams.js

@@ -26,8 +26,7 @@ async function createSSGParams({ props, serverBundlePath, clientManifestPath, })
         noIndex: props.siteConfig.noIndex,
         DOCUSAURUS_VERSION: utils_1.DOCUSAURUS_VERSION,
         serverBundlePath,
-        htmlMinifierType: props.siteConfig.future.experimental_faster
-            .swcHtmlMinimizer
+        htmlMinifierType: props.siteConfig.future.faster.swcHtmlMinimizer
             ? 'swc'
             : 'terser',
         v4RemoveLegacyPostBuildHeadAttribute: props.siteConfig.future.v4.removeLegacyPostBuildHeadAttribute,

package/lib/webpack/aliases/index.js

@@ -39,6 +39,13 @@ async function createAliasesForTheme(themePath, addOriginalAlias) {
     }
     const themeComponentFiles = await (0, utils_1.Globby)(['**/*.{js,jsx,ts,tsx}'], {
         cwd: themePath,
+        ignore: [
+            // Ignore co-located test files
+            '**/__tests__/**',
+            '**/*.test.{js,jsx,ts,tsx}',
+            // Ignore type declaration files
+            '**/*.d.ts',
+        ],
     });
     const aliases = {};
     themeComponentFiles.forEach((relativeSource) => {

package/lib/webpack/base.js

@@ -86,7 +86,7 @@ async function createBaseConfig({ props, isServer, minify, faster, configureWebp
             return disabledPersistentCacheValue;
         }
         if (props.currentBundler.name === 'rspack') {
-            if (props.siteConfig.future.experimental_faster.rspackPersistentCache) {
+            if (props.siteConfig.future.faster.rspackPersistentCache) {
                 // Use cache: true + experiments.cache.type: "persistent"
                 // See https://rspack.dev/config/experiments#persistent-cache
                 return true;
@@ -118,24 +118,6 @@ async function createBaseConfig({ props, isServer, minify, faster, configureWebp
                     buildDependencies: getCacheBuildDependencies(),
                 };
             }
-            if (process.env.DISABLE_RSPACK_INCREMENTAL) {
-                // Enabled by default since Rspack 1.4
-                console.log('Rspack incremental disabled');
-                experiments.incremental = false;
-            }
-            // See https://rspack.rs/blog/announcing-1-5#barrel-file-optimization
-            if (process.env.DISABLE_RSPACK_LAZY_BARREL) {
-                console.log('Rspack lazyBarrel disabled');
-                experiments.lazyBarrel = false;
-            }
-            else {
-                // TODO remove after we upgrade to Rspack 1.6+
-                //  Enabled by default for Rspack >= 1.6
-                experiments.lazyBarrel = true;
-            }
-            // TODO re-enable later, there's an Rspack performance issue
-            //  see https://github.com/facebook/docusaurus/pull/11178
-            experiments.parallelCodeSplitting = false;
             return experiments;
         }
         return undefined;

package/lib/webpack/server.js

@@ -18,7 +18,7 @@ async function createServerConfig({ props, configureWebpackUtils, }) {
         props,
         isServer: true,
         minify: false,
-        faster: props.siteConfig.future.experimental_faster,
+        faster: props.siteConfig.future.faster,
         configureWebpackUtils,
     });
     const ProgressBarPlugin = await (0, bundler_1.getProgressBarPlugin)({

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "3.9.1",
+  "version": "3.9.2-alpha.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -33,13 +33,13 @@
     "url": "https://github.com/facebook/docusaurus/issues"
   },
   "dependencies": {
-    "@docusaurus/babel": "3.9.1",
-    "@docusaurus/bundler": "3.9.1",
-    "@docusaurus/logger": "3.9.1",
-    "@docusaurus/mdx-loader": "3.9.1",
-    "@docusaurus/utils": "3.9.1",
-    "@docusaurus/utils-common": "3.9.1",
-    "@docusaurus/utils-validation": "3.9.1",
+    "@docusaurus/babel": "3.9.2-alpha.0",
+    "@docusaurus/bundler": "3.9.2-alpha.0",
+    "@docusaurus/logger": "3.9.2-alpha.0",
+    "@docusaurus/mdx-loader": "3.9.2-alpha.0",
+    "@docusaurus/utils": "3.9.2-alpha.0",
+    "@docusaurus/utils-common": "3.9.2-alpha.0",
+    "@docusaurus/utils-validation": "3.9.2-alpha.0",
     "boxen": "^6.2.1",
     "chalk": "^4.1.2",
     "chokidar": "^3.5.3",
@@ -51,7 +51,7 @@
     "escape-html": "^1.0.3",
     "eta": "^2.2.0",
     "eval": "^0.1.8",
-    "execa": "5.1.1",
+    "execa": "^5.1.1",
     "fs-extra": "^11.1.1",
     "html-tags": "^3.3.1",
     "html-webpack-plugin": "^5.6.0",
@@ -77,26 +77,31 @@
     "webpack-merge": "^6.0.1"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.9.1",
-    "@docusaurus/types": "3.9.1",
+    "@docusaurus/module-type-aliases": "3.9.2-alpha.0",
+    "@docusaurus/types": "3.9.2-alpha.0",
     "@total-typescript/shoehorn": "^0.1.2",
     "@types/detect-port": "^1.3.3",
-    "@types/react-dom": "^18.2.7",
+    "@types/react-dom": "^19.2.3",
     "@types/react-router-config": "^5.0.7",
     "@types/serve-handler": "^6.1.4",
     "@types/update-notifier": "^6.0.4",
     "@types/webpack-bundle-analyzer": "^4.7.0",
-    "react-test-renderer": "^18.0.0",
     "tmp-promise": "^3.0.3",
     "tree-node-cli": "^1.6.0"
   },
   "peerDependencies": {
+    "@docusaurus/faster": "*",
     "@mdx-js/react": "^3.0.0",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0"
   },
+  "peerDependenciesMeta": {
+    "@docusaurus/faster": {
+      "optional": true
+    }
+  },
   "engines": {
     "node": ">=20.0"
   },
-  "gitHead": "c0dd59f0e712f85b6053c59e46b0514b5d2d1414"
+  "gitHead": "27626cdd7a102277935f10cc4d8d3f93e211eafe"
 }