@docusaurus/core 3.3.2 → 3.4.0

package/lib/client/clientEntry.js

@@ -6,12 +6,16 @@
  */
 import React, { startTransition } from 'react';
 import ReactDOM from 'react-dom/client';
-import { BrowserRouter } from 'react-router-dom';
 import { HelmetProvider } from 'react-helmet-async';
+import { BrowserRouter, HashRouter } from 'react-router-dom';
+import siteConfig from '@generated/docusaurus.config';
 import ExecutionEnvironment from './exports/ExecutionEnvironment';
 import App from './App';
 import preload from './preload';
 import docusaurus from './docusaurus';
+function Router({ children }) {
+    return siteConfig.future.experimental_router === 'hash' ? (<HashRouter>{children}</HashRouter>) : (<BrowserRouter>{children}</BrowserRouter>);
+}
 const hydrate = Boolean(process.env.HYDRATE_CLIENT_ENTRY);
 // Client-side render (e.g: running in browser) to become single-page
 // application (SPA).
@@ -19,9 +23,9 @@ if (ExecutionEnvironment.canUseDOM) {
     window.docusaurus = docusaurus;
     const container = document.getElementById('__docusaurus');
     const app = (<HelmetProvider>
-      <BrowserRouter>
+      <Router>
         <App />
-      </BrowserRouter>
+      </Router>
     </HelmetProvider>);
     const onRecoverableError = (error, errorInfo) => {
         console.error('Docusaurus React Root onRecoverableError:', error, errorInfo);

package/lib/client/exports/Link.js

@@ -19,7 +19,9 @@ import { useBaseUrlUtils } from './useBaseUrl';
 // like "introduction" to "/baseUrl/introduction" => bad behavior to fix
 const shouldAddBaseUrlAutomatically = (to) => to.startsWith('/');
 function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLinkCheck': noBrokenLinkCheck, autoAddBaseUrl = true, ...props }, forwardedRef) {
-    const { siteConfig: { trailingSlash, baseUrl }, } = useDocusaurusContext();
+    const { siteConfig } = useDocusaurusContext();
+    const { trailingSlash, baseUrl } = siteConfig;
+    const router = siteConfig.future.experimental_router;
     const { withBaseUrl } = useBaseUrlUtils();
     const brokenLinks = useBrokenLinks();
     const innerRef = useRef(null);
@@ -47,6 +49,14 @@ function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLi
     let targetLink = typeof targetLinkWithoutPathnameProtocol !== 'undefined'
         ? maybeAddBaseUrl(targetLinkWithoutPathnameProtocol)
         : undefined;
+    // TODO find a way to solve this problem properly
+    // Fix edge case when useBaseUrl is used on a link
+    // "./" is useful for images and other resources
+    // But we don't need it for <Link>
+    // unfortunately we can't really make the difference :/
+    if (router === 'hash' && targetLink?.startsWith('./')) {
+        targetLink = targetLink?.slice(1);
+    }
     if (targetLink && isInternal) {
         targetLink = applyTrailingSlash(targetLink, { trailingSlash, baseUrl });
     }
@@ -103,7 +113,7 @@ function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLi
     // https://github.com/remix-run/react-router/blob/v5/packages/react-router-dom/modules/Link.js#L47
     const hasInternalTarget = !props.target || props.target === '_self';
     // Should we use a regular <a> tag instead of React-Router Link component?
-    const isRegularHtmlLink = !targetLink || !isInternal || !hasInternalTarget || isAnchorLink;
+    const isRegularHtmlLink = !targetLink || !isInternal || !hasInternalTarget;
     if (!noBrokenLinkCheck && (isAnchorLink || !isRegularHtmlLink)) {
         brokenLinks.collectLink(targetLink);
     }

package/lib/client/exports/useBaseUrl.d.ts

@@ -6,5 +6,13 @@
  */
 /// <reference types="@docusaurus/module-type-aliases" />
 import type { BaseUrlOptions, BaseUrlUtils } from '@docusaurus/useBaseUrl';
+import type { RouterType } from '@docusaurus/types';
+export declare function addBaseUrl({ siteUrl, baseUrl, url, options: { forcePrependBaseUrl, absolute }, router, }: {
+    siteUrl: string;
+    baseUrl: string;
+    url: string;
+    router: RouterType;
+    options?: BaseUrlOptions;
+}): string;
 export declare function useBaseUrlUtils(): BaseUrlUtils;
 export default function useBaseUrl(url: string, options?: BaseUrlOptions): string;

package/lib/client/exports/useBaseUrl.js

@@ -7,12 +7,18 @@
 import { useCallback } from 'react';
 import useDocusaurusContext from './useDocusaurusContext';
 import { hasProtocol } from './isInternalUrl';
-function addBaseUrl(siteUrl, baseUrl, url, { forcePrependBaseUrl = false, absolute = false } = {}) {
+export function addBaseUrl({ siteUrl, baseUrl, url, options: { forcePrependBaseUrl = false, absolute = false } = {}, router, }) {
     // It never makes sense to add base url to a local anchor url, or one with a
     // protocol
     if (!url || url.startsWith('#') || hasProtocol(url)) {
         return url;
     }
+    // TODO hash router + /baseUrl/ is unlikely to work well in all situations
+    // This will support most cases, but not all
+    // See https://github.com/facebook/docusaurus/pull/9859
+    if (router === 'hash') {
+        return url.startsWith('/') ? `.${url}` : `./${url}`;
+    }
     if (forcePrependBaseUrl) {
         return baseUrl + url.replace(/^\//, '');
     }
@@ -27,8 +33,10 @@ function addBaseUrl(siteUrl, baseUrl, url, { forcePrependBaseUrl = false, absolu
     return absolute ? siteUrl + basePath : basePath;
 }
 export function useBaseUrlUtils() {
-    const { siteConfig: { baseUrl, url: siteUrl }, } = useDocusaurusContext();
-    const withBaseUrl = useCallback((url, options) => addBaseUrl(siteUrl, baseUrl, url, options), [siteUrl, baseUrl]);
+    const { siteConfig } = useDocusaurusContext();
+    const { baseUrl, url: siteUrl } = siteConfig;
+    const router = siteConfig.future.experimental_router;
+    const withBaseUrl = useCallback((url, options) => addBaseUrl({ siteUrl, baseUrl, url, options, router }), [siteUrl, baseUrl, router]);
     return {
         withBaseUrl,
     };

package/lib/commands/build.js

@@ -17,6 +17,7 @@ const site_1 = require("../server/site");
 const brokenLinks_1 = require("../server/brokenLinks");
 const client_1 = require("../webpack/client");
 const server_1 = tslib_1.__importDefault(require("../webpack/server"));
+const configure_1 = require("../webpack/configure");
 const utils_2 = require("../webpack/utils");
 const utils_3 = require("../utils");
 const i18n_1 = require("../server/i18n");
@@ -110,7 +111,8 @@ async function buildLocale({ siteDir, locale, cliOptions, }) {
         localizePath: cliOptions.locale ? false : undefined,
     }));
     const { props } = site;
-    const { outDir, plugins } = props;
+    const { outDir, plugins, siteConfig } = props;
+    const router = siteConfig.future.experimental_router;
     // We can build the 2 configs in parallel
     const [{ clientConfig, clientManifestPath }, { serverConfig, serverBundlePath }] = await utils_3.PerfLogger.async('Creating webpack configs', () => Promise.all([
         getBuildClientConfig({
@@ -122,11 +124,19 @@ async function buildLocale({ siteDir, locale, cliOptions, }) {
         }),
     ]));
     // Run webpack to build JS bundle (client) and static html files (server).
-    await utils_3.PerfLogger.async('Bundling with Webpack', () => (0, utils_2.compile)([clientConfig, serverConfig]));
+    await utils_3.PerfLogger.async('Bundling with Webpack', () => {
+        if (router === 'hash') {
+            return (0, utils_2.compile)([clientConfig]);
+        }
+        else {
+            return (0, utils_2.compile)([clientConfig, serverConfig]);
+        }
+    });
     const { collectedData } = await utils_3.PerfLogger.async('SSG', () => executeSSG({
         props,
         serverBundlePath,
         clientManifestPath,
+        router,
     }));
     // Remove server.bundle.js because it is not needed.
     await utils_3.PerfLogger.async('Deleting server bundle', () => ensureUnlink(serverBundlePath));
@@ -137,27 +147,35 @@ async function buildLocale({ siteDir, locale, cliOptions, }) {
     logger_1.default.success `Generated static files in path=${path_1.default.relative(process.cwd(), outDir)}.`;
     return outDir;
 }
-async function executeSSG({ props, serverBundlePath, clientManifestPath, }) {
+async function executeSSG({ props, serverBundlePath, clientManifestPath, router, }) {
     const manifest = await utils_3.PerfLogger.async('Read client manifest', () => fs_extra_1.default.readJSON(clientManifestPath, 'utf-8'));
     const ssrTemplate = await utils_3.PerfLogger.async('Compile SSR template', () => (0, templates_1.compileSSRTemplate)(props.siteConfig.ssrTemplate ?? ssr_html_template_1.default));
+    const params = {
+        trailingSlash: props.siteConfig.trailingSlash,
+        outDir: props.outDir,
+        baseUrl: props.baseUrl,
+        manifest,
+        headTags: props.headTags,
+        preBodyTags: props.preBodyTags,
+        postBodyTags: props.postBodyTags,
+        ssrTemplate,
+        noIndex: props.siteConfig.noIndex,
+        DOCUSAURUS_VERSION: utils_1.DOCUSAURUS_VERSION,
+    };
+    if (router === 'hash') {
+        utils_3.PerfLogger.start('Generate Hash Router entry point');
+        const content = (0, templates_1.renderHashRouterTemplate)({ params });
+        await (0, ssg_1.generateHashRouterEntrypoint)({ content, params });
+        utils_3.PerfLogger.end('Generate Hash Router entry point');
+        return { collectedData: {} };
+    }
     const renderer = await utils_3.PerfLogger.async('Load App renderer', () => (0, ssg_1.loadAppRenderer)({
         serverBundlePath,
     }));
     const ssgResult = await utils_3.PerfLogger.async('Generate static files', () => (0, ssg_1.generateStaticFiles)({
         pathnames: props.routesPaths,
         renderer,
-        params: {
-            trailingSlash: props.siteConfig.trailingSlash,
-            outDir: props.outDir,
-            baseUrl: props.baseUrl,
-            manifest,
-            headTags: props.headTags,
-            preBodyTags: props.preBodyTags,
-            postBodyTags: props.postBodyTags,
-            ssrTemplate,
-            noIndex: props.siteConfig.noIndex,
-            DOCUSAURUS_VERSION: utils_1.DOCUSAURUS_VERSION,
-        },
+        params,
     }));
     return ssgResult;
 }
@@ -194,11 +212,7 @@ async function getBuildClientConfig({ props, cliOptions, }) {
         bundleAnalyzer: cliOptions.bundleAnalyzer ?? false,
     });
     let { config } = result;
-    config = (0, utils_2.executePluginsConfigurePostCss)({
-        plugins,
-        config,
-    });
-    config = (0, utils_2.executePluginsConfigureWebpack)({
+    config = (0, configure_1.executePluginsConfigureWebpack)({
         plugins,
         config,
         isServer: false,
@@ -212,7 +226,7 @@ async function getBuildServerConfig({ props }) {
         props,
     });
     let { config } = result;
-    config = (0, utils_2.executePluginsConfigureWebpack)({
+    config = (0, configure_1.executePluginsConfigureWebpack)({
         plugins,
         config,
         isServer: true,

package/lib/commands/serve.js

@@ -52,10 +52,21 @@ async function serve(siteDirParam = '.', cliOptions = {}) {
         }
         // We do the redirect ourselves for a good reason
         // server-handler is annoying and won't include /baseUrl/ in redirects
-        const normalizedUrl = (0, utils_common_1.applyTrailingSlash)(req.url, { trailingSlash, baseUrl });
-        if (req.url !== normalizedUrl) {
-            redirect(res, normalizedUrl);
-            return;
+        // See https://github.com/facebook/docusaurus/issues/10078#issuecomment-2084932934
+        if (baseUrl !== '/') {
+            // Not super robust, but should be good enough for our use case
+            // See https://github.com/facebook/docusaurus/pull/10090
+            const looksLikeAsset = !!req.url.match(/.[a-zA-Z\d]{1,4}$/);
+            if (!looksLikeAsset) {
+                const normalizedUrl = (0, utils_common_1.applyTrailingSlash)(req.url, {
+                    trailingSlash,
+                    baseUrl,
+                });
+                if (req.url !== normalizedUrl) {
+                    redirect(res, normalizedUrl);
+                    return;
+                }
+            }
         }
         // Remove baseUrl before calling serveHandler, because /baseUrl/ should
         // serve /build/index.html, not /build/baseUrl/index.html (does not exist)

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

@@ -6,12 +6,13 @@
  */
 import _ from 'lodash';
 import type { StartCLIOptions } from './start';
-import type { LoadedPlugin } from '@docusaurus/types';
+import type { LoadedPlugin, RouterType } from '@docusaurus/types';
 export type OpenUrlContext = {
     host: string;
     port: number;
-    getOpenUrl: ({ baseUrl }: {
+    getOpenUrl: ({ baseUrl, router, }: {
         baseUrl: string;
+        router: RouterType;
     }) => string;
 };
 export declare function createOpenUrlContext({ cliOptions, }: {

package/lib/commands/start/utils.js

@@ -23,9 +23,13 @@ async function createOpenUrlContext({ cliOptions, }) {
     if (port === null) {
         return process.exit();
     }
-    const getOpenUrl = ({ baseUrl }) => {
+    const getOpenUrl = ({ baseUrl, router }) => {
         const urls = (0, WebpackDevServerUtils_1.prepareUrls)(protocol, host, port);
-        return (0, utils_1.normalizeUrl)([urls.localUrlForBrowser, baseUrl]);
+        return (0, utils_1.normalizeUrl)([
+            urls.localUrlForBrowser,
+            router === 'hash' ? '/#/' : '',
+            baseUrl,
+        ]);
     };
     return { host, port, getOpenUrl };
 }
@@ -47,6 +51,7 @@ async function createReloadableSite(startParams) {
     const get = () => site;
     const getOpenUrl = () => openUrlContext.getOpenUrl({
         baseUrl: site.props.baseUrl,
+        router: site.props.siteConfig.future.experimental_router,
     });
     const printOpenUrlMessage = () => {
         logger_1.default.success `Docusaurus website is running at: url=${getOpenUrl()}`;

package/lib/commands/start/webpack.js

@@ -16,6 +16,7 @@ const webpack_dev_server_1 = tslib_1.__importDefault(require("webpack-dev-server
 const evalSourceMapMiddleware_1 = tslib_1.__importDefault(require("react-dev-utils/evalSourceMapMiddleware"));
 const watcher_1 = require("./watcher");
 const utils_1 = require("../../webpack/utils");
+const configure_1 = require("../../webpack/configure");
 const client_1 = require("../../webpack/client");
 // E2E_TEST=true docusaurus start
 // Makes "docusaurus start" exit immediately on success/error, for E2E test
@@ -60,7 +61,7 @@ async function createDevServerConfig({ cliOptions, props, host, port, }) {
             'access-control-allow-origin': '*',
         },
         devMiddleware: {
-            publicPath: baseUrl,
+            publicPath: siteConfig.future.experimental_router === 'hash' ? 'auto' : baseUrl,
             // Reduce log verbosity, see https://github.com/facebook/docusaurus/pull/5420#issuecomment-906613105
             stats: 'summary',
         },
@@ -103,8 +104,7 @@ async function getStartClientConfig({ props, minify, poll, }) {
         minify,
         poll,
     });
-    config = (0, utils_1.executePluginsConfigurePostCss)({ plugins, config });
-    config = (0, utils_1.executePluginsConfigureWebpack)({
+    config = (0, configure_1.executePluginsConfigureWebpack)({
         plugins,
         config,
         isServer: false,

package/lib/server/brokenLinks.js

@@ -78,7 +78,15 @@ function createBrokenLinksHelper({ collectedLinks, routes, }) {
         if (hash === '') {
             return false;
         }
-        const targetPage = collectedLinks.get(pathname) || collectedLinks.get(decodeURI(pathname));
+        const targetPage = collectedLinks.get(pathname) ??
+            collectedLinks.get(decodeURI(pathname)) ??
+            // The broken link checker should not care about a trailing slash
+            // Those are already covered by the broken pathname checker
+            // See https://github.com/facebook/docusaurus/issues/10116
+            collectedLinks.get((0, utils_common_1.addTrailingSlash)(pathname)) ??
+            collectedLinks.get((0, utils_common_1.addTrailingSlash)(decodeURI(pathname))) ??
+            collectedLinks.get((0, utils_common_1.removeTrailingSlash)(pathname)) ??
+            collectedLinks.get((0, utils_common_1.removeTrailingSlash)(decodeURI(pathname)));
         // link with anchor to a page that does not exist (or did not collect any
         // link/anchor) is considered as a broken anchor
         if (!targetPage) {

package/lib/server/codegen/codegen.d.ts

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import type { CodeTranslations, DocusaurusConfig, GlobalData, I18n, PluginRouteConfig, SiteMetadata } from '@docusaurus/types';
+import type { CodeTranslations, DocusaurusConfig, GlobalData, I18n, PluginRouteConfig, SiteMetadata, SiteStorage } from '@docusaurus/types';
 type CodegenParams = {
     generatedFilesDir: string;
     siteConfig: DocusaurusConfig;
@@ -14,6 +14,7 @@ type CodegenParams = {
     i18n: I18n;
     codeTranslations: CodeTranslations;
     siteMetadata: SiteMetadata;
+    siteStorage: SiteStorage;
     routes: PluginRouteConfig[];
 };
 export declare function generateSiteFiles(params: CodegenParams): Promise<void>;

package/lib/server/codegen/codegen.js

@@ -50,6 +50,9 @@ function genCodeTranslations({ generatedFilesDir, codeTranslations, }) {
 function genSiteMetadata({ generatedFilesDir, siteMetadata, }) {
     return (0, utils_1.generate)(generatedFilesDir, 'site-metadata.json', JSON.stringify(siteMetadata, null, 2));
 }
+function genSiteStorage({ generatedFilesDir, siteStorage, }) {
+    return (0, utils_1.generate)(generatedFilesDir, 'site-storage.json', JSON.stringify(siteStorage, null, 2));
+}
 async function generateSiteFiles(params) {
     await Promise.all([
         genWarning(params),
@@ -58,6 +61,7 @@ async function generateSiteFiles(params) {
         (0, codegenRoutes_1.generateRouteFiles)(params),
         genGlobalData(params),
         genSiteMetadata(params),
+        genSiteStorage(params),
         genI18n(params),
         genCodeTranslations(params),
     ]);

package/lib/server/codegen/codegenRoutes.d.ts

@@ -45,5 +45,6 @@ type GenerateRouteFilesParams = {
     routes: PluginRouteConfig[];
     baseUrl: string;
 };
+export declare function generateRoutePropFilename(route: RouteConfig): string;
 export declare function generateRouteFiles({ generatedFilesDir, routes: initialRoutes, }: GenerateRouteFilesParams): Promise<void>;
 export {};

package/lib/server/codegen/codegenRoutes.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.generateRouteFiles = exports.generateRoutesCode = exports.genChunkName = void 0;
+exports.generateRouteFiles = exports.generateRoutePropFilename = exports.generateRoutesCode = exports.genChunkName = void 0;
 const tslib_1 = require("tslib");
 const querystring_1 = tslib_1.__importDefault(require("querystring"));
 const path_1 = tslib_1.__importDefault(require("path"));
@@ -180,12 +180,26 @@ ${Object.entries(registry)
 `);
 const genRoutesChunkNames = ({ generatedFilesDir, routesChunkNames, }) => (0, utils_1.generate)(generatedFilesDir, 'routesChunkNames.json', JSON.stringify(routesChunkNames, null, 2));
 const genRoutes = ({ generatedFilesDir, routesConfig, }) => (0, utils_1.generate)(generatedFilesDir, 'routes.js', routesConfig);
+// The generated filename per route must be unique to avoid conflicts
+// See also https://github.com/facebook/docusaurus/issues/10125
+function generateRoutePropFilename(route) {
+    // TODO if possible, we could try to shorten the filename by removing
+    //  the plugin routeBasePath prefix from the name
+    return `${(0, utils_1.docuHash)(route.path, 
+    // Note: using hash(route.path + route.component) is not technically
+    // as robust as hashing the entire prop content object.
+    // But it's faster and should be good enough considering it's very unlikely
+    // anyone would have 2 routes on the same path also rendering the exact
+    // same component.
+    { hashExtra: route.component })}.json`;
+}
+exports.generateRoutePropFilename = generateRoutePropFilename;
 async function generateRoutePropModule({ generatedFilesDir, route, plugin, }) {
     ensureNoPropsConflict(route);
     const moduleContent = JSON.stringify(route.props);
     // TODO we should aim to reduce this path length
     // This adds bytes to the global module registry
-    const relativePath = path_1.default.posix.join(plugin.name, plugin.id, 'p', `${(0, utils_1.docuHash)(route.path)}.json`);
+    const relativePath = path_1.default.posix.join(plugin.name, plugin.id, 'p', generateRoutePropFilename(route));
     const modulePath = path_1.default.posix.join(generatedFilesDir, relativePath);
     const aliasedPath = path_1.default.posix.join('@generated', relativePath);
     await (0, utils_1.generate)(generatedFilesDir, modulePath, moduleContent);
@@ -201,14 +215,14 @@ function ensureNoPropsConflict(route) {
     }
 }
 async function preprocessRouteProps({ generatedFilesDir, route, plugin, }) {
-    const propsModulePathPromise = route.props
+    const getPropsModulePathPromise = () => route.props
         ? generateRoutePropModule({
             generatedFilesDir,
             route,
             plugin,
         })
         : undefined;
-    const subRoutesPromise = route.routes
+    const getSubRoutesPromise = () => route.routes
         ? Promise.all(route.routes.map((subRoute) => {
             return preprocessRouteProps({
                 generatedFilesDir,
@@ -218,8 +232,8 @@ async function preprocessRouteProps({ generatedFilesDir, route, plugin, }) {
         }))
         : undefined;
     const [propsModulePath, subRoutes] = await Promise.all([
-        propsModulePathPromise,
-        subRoutesPromise,
+        getPropsModulePathPromise(),
+        getSubRoutesPromise(),
     ]);
     const newRoute = {
         ...route,

package/lib/server/configValidation.d.ts

@@ -5,9 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Joi } from '@docusaurus/utils-validation';
+import type { FutureConfig, StorageConfig } from '@docusaurus/types/src/config';
 import type { DocusaurusConfig, I18nConfig, MarkdownConfig } from '@docusaurus/types';
 export declare const DEFAULT_I18N_CONFIG: I18nConfig;
+export declare const DEFAULT_STORAGE_CONFIG: StorageConfig;
+export declare const DEFAULT_FUTURE_CONFIG: FutureConfig;
 export declare const DEFAULT_MARKDOWN_CONFIG: MarkdownConfig;
-export declare const DEFAULT_CONFIG: Pick<DocusaurusConfig, 'i18n' | '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' | '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

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateConfig = exports.ConfigSchema = exports.DEFAULT_CONFIG = exports.DEFAULT_MARKDOWN_CONFIG = exports.DEFAULT_I18N_CONFIG = void 0;
+exports.validateConfig = exports.ConfigSchema = exports.DEFAULT_CONFIG = exports.DEFAULT_MARKDOWN_CONFIG = exports.DEFAULT_FUTURE_CONFIG = exports.DEFAULT_STORAGE_CONFIG = exports.DEFAULT_I18N_CONFIG = void 0;
 const utils_1 = require("@docusaurus/utils");
 const utils_validation_1 = require("@docusaurus/utils-validation");
 const utils_common_1 = require("@docusaurus/utils-common");
@@ -17,6 +17,14 @@ exports.DEFAULT_I18N_CONFIG = {
     locales: [DEFAULT_I18N_LOCALE],
     localeConfigs: {},
 };
+exports.DEFAULT_STORAGE_CONFIG = {
+    type: 'localStorage',
+    namespace: false,
+};
+exports.DEFAULT_FUTURE_CONFIG = {
+    experimental_storage: exports.DEFAULT_STORAGE_CONFIG,
+    experimental_router: 'browser',
+};
 exports.DEFAULT_MARKDOWN_CONFIG = {
     format: 'mdx', // TODO change this to "detect" in Docusaurus v4?
     mermaid: false,
@@ -34,6 +42,7 @@ exports.DEFAULT_MARKDOWN_CONFIG = {
 };
 exports.DEFAULT_CONFIG = {
     i18n: exports.DEFAULT_I18N_CONFIG,
+    future: exports.DEFAULT_FUTURE_CONFIG,
     onBrokenLinks: 'throw',
     onBrokenAnchors: 'warn', // TODO Docusaurus v4: change to throw
     onBrokenMarkdownLinks: 'warn',
@@ -120,6 +129,24 @@ const I18N_CONFIG_SCHEMA = utils_validation_1.Joi.object({
 })
     .optional()
     .default(exports.DEFAULT_I18N_CONFIG);
+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),
+})
+    .optional()
+    .default(exports.DEFAULT_STORAGE_CONFIG);
+const FUTURE_CONFIG_SCHEMA = utils_validation_1.Joi.object({
+    experimental_storage: STORAGE_CONFIG_SCHEMA,
+    experimental_router: utils_validation_1.Joi.string()
+        .equal('browser', 'hash')
+        .default(exports.DEFAULT_FUTURE_CONFIG.experimental_router),
+})
+    .optional()
+    .default(exports.DEFAULT_FUTURE_CONFIG);
 const SiteUrlSchema = utils_validation_1.Joi.string()
     .required()
     .custom((value, helpers) => {
@@ -152,6 +179,7 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
     url: SiteUrlSchema,
     trailingSlash: utils_validation_1.Joi.boolean(), // No default value! undefined = retrocompatible legacy behavior!
     i18n: I18N_CONFIG_SCHEMA,
+    future: FUTURE_CONFIG_SCHEMA,
     onBrokenLinks: utils_validation_1.Joi.string()
         .equal('ignore', 'log', 'warn', 'throw')
         .default(exports.DEFAULT_CONFIG.onBrokenLinks),

package/lib/server/htmlTags.d.ts

@@ -4,9 +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 { Props, LoadedPlugin } from '@docusaurus/types';
+import type { Props, LoadedPlugin, RouterType } 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'>;
+export declare function loadHtmlTags({ plugins, router, }: {
+    plugins: LoadedPlugin[];
+    router: RouterType;
+}): Pick<Props, 'headTags' | 'preBodyTags' | 'postBodyTags'>;

package/lib/server/htmlTags.js

@@ -23,16 +23,25 @@ function assertIsHtmlTagObject(val) {
         throw new Error(`Error loading ${JSON.stringify(val)}, "${val.tagName}" is not a valid HTML tag.`);
     }
 }
-function htmlTagObjectToString(tag) {
+function hashRouterAbsoluteToRelativeTagAttribute(name, value) {
+    if ((name === 'src' || name === 'href') && value.startsWith('/')) {
+        return `.${value}`;
+    }
+    return value;
+}
+function htmlTagObjectToString({ tag, router, }) {
     assertIsHtmlTagObject(tag);
     const isVoidTag = void_1.default.includes(tag.tagName);
     const tagAttributes = tag.attributes ?? {};
     const attributes = Object.keys(tagAttributes)
         .map((attr) => {
-        const value = tagAttributes[attr];
+        let value = tagAttributes[attr];
         if (typeof value === 'boolean') {
             return value ? attr : undefined;
         }
+        if (router === 'hash') {
+            value = hashRouterAbsoluteToRelativeTagAttribute(attr, value);
+        }
         return `${attr}="${(0, escape_html_1.default)(value)}"`;
     })
         .filter((str) => Boolean(str));
@@ -41,21 +50,21 @@ function htmlTagObjectToString(tag) {
     const closingTag = isVoidTag ? '' : `</${tag.tagName}>`;
     return openingTag + innerHTML + closingTag;
 }
-function createHtmlTagsString(tags) {
+function createHtmlTagsString({ tags, router, }) {
     return (Array.isArray(tags) ? tags : [tags])
         .filter(Boolean)
-        .map((val) => (typeof val === 'string' ? val : htmlTagObjectToString(val)))
+        .map((val) => typeof val === 'string' ? val : htmlTagObjectToString({ tag: val, router }))
         .join('\n');
 }
 /**
  * Runs the `injectHtmlTags` lifecycle, and aggregates all plugins' tags into
  * directly render-able HTML markup.
  */
-function loadHtmlTags(plugins) {
+function loadHtmlTags({ plugins, router, }) {
     const pluginHtmlTags = plugins.map((plugin) => plugin.injectHtmlTags?.({ content: plugin.content }) ?? {});
     const tagTypes = ['headTags', 'preBodyTags', 'postBodyTags'];
     return Object.fromEntries(lodash_1.default.zip(tagTypes, tagTypes.map((type) => pluginHtmlTags
-        .map((tags) => createHtmlTagsString(tags[type]))
+        .map((tags) => createHtmlTagsString({ tags: tags[type], router }))
         .join('\n')
         .trim())));
 }