@docusaurus/core 3.0.1 → 3.1.1

package/bin/docusaurus.mjs

@@ -218,6 +218,9 @@ cli.arguments('<command>').action((cmd) => {
   logger.error`    Unknown command name=${cmd}.`;
 });
 
+// === The above is the commander configuration ===
+// They don't start any code execution yet until cli.parse() is called below
+
 /**
  * @param {string | undefined} command
  */
@@ -237,12 +240,29 @@ function isInternalCommand(command) {
   );
 }
 
-if (!isInternalCommand(process.argv.slice(2)[0])) {
-  await externalCommand(cli);
-}
+// process.argv always looks like this:
+// [
+//   '/path/to/node',
+//   '/path/to/docusaurus.mjs',
+//   '<subcommand>',
+//   ...subcommandArgs
+// ]
 
-if (!process.argv.slice(2).length) {
+// There is no subcommand
+// TODO: can we use commander to handle this case?
+if (process.argv.length < 3 || process.argv[2]?.startsWith('--')) {
   cli.outputHelp();
+  process.exit(1);
+}
+
+// There is an unrecognized subcommand
+// Let plugins extend the CLI before parsing
+if (!isInternalCommand(process.argv[2])) {
+  // TODO: in this step, we must assume default site structure because there's
+  // no way to know the siteDir/config yet. Maybe the root cli should be
+  // responsible for parsing these arguments?
+  // https://github.com/facebook/docusaurus/issues/8903
+  await externalCommand(cli);
 }
 
 cli.parse(process.argv);

package/lib/client/BrokenLinksContext.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 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.
+ */
+/// <reference types="@docusaurus/module-type-aliases" />
+import { type ReactNode } from 'react';
+import type { BrokenLinks } from '@docusaurus/useBrokenLinks';
+export type StatefulBrokenLinks = BrokenLinks & {
+    getCollectedLinks: () => string[];
+    getCollectedAnchors: () => string[];
+};
+export declare const createStatefulBrokenLinks: () => StatefulBrokenLinks;
+export declare const useBrokenLinksContext: () => BrokenLinks;
+export declare function BrokenLinksProvider({ children, brokenLinks, }: {
+    children: ReactNode;
+    brokenLinks: BrokenLinks;
+}): JSX.Element;

package/lib/client/BrokenLinksContext.js

@@ -0,0 +1,34 @@
+/**
+ * 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 React, { useContext } from 'react';
+export const createStatefulBrokenLinks = () => {
+    // Set to dedup, as it's not useful to collect multiple times the same value
+    const allAnchors = new Set();
+    const allLinks = new Set();
+    return {
+        collectAnchor: (anchor) => {
+            typeof anchor !== 'undefined' && allAnchors.add(anchor);
+        },
+        collectLink: (link) => {
+            typeof link !== 'undefined' && allLinks.add(link);
+        },
+        getCollectedAnchors: () => [...allAnchors],
+        getCollectedLinks: () => [...allLinks],
+    };
+};
+const Context = React.createContext({
+    collectAnchor: () => {
+        // No-op for client
+    },
+    collectLink: () => {
+        // No-op for client
+    },
+});
+export const useBrokenLinksContext = () => useContext(Context);
+export function BrokenLinksProvider({ children, brokenLinks, }) {
+    return <Context.Provider value={brokenLinks}>{children}</Context.Provider>;
+}

package/lib/client/exports/Link.js

@@ -10,7 +10,7 @@ import { applyTrailingSlash } from '@docusaurus/utils-common';
 import useDocusaurusContext from './useDocusaurusContext';
 import isInternalUrl from './isInternalUrl';
 import ExecutionEnvironment from './ExecutionEnvironment';
-import { useLinksCollector } from '../LinksCollector';
+import useBrokenLinks from './useBrokenLinks';
 import { useBaseUrlUtils } from './useBaseUrl';
 // TODO all this wouldn't be necessary if we used ReactRouter basename feature
 // We don't automatically add base urls to all links,
@@ -21,7 +21,7 @@ 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 { withBaseUrl } = useBaseUrlUtils();
-    const linksCollector = useLinksCollector();
+    const brokenLinks = useBrokenLinks();
     const innerRef = useRef(null);
     useImperativeHandle(forwardedRef, () => innerRef.current);
     // IMPORTANT: using to or href should not change anything
@@ -97,10 +97,18 @@ function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLi
             }
         };
     }, [ioRef, targetLink, IOSupported, isInternal]);
+    // It is simple local anchor link targeting current page?
     const isAnchorLink = targetLink?.startsWith('#') ?? false;
-    const isRegularHtmlLink = !targetLink || !isInternal || isAnchorLink;
-    if (!isRegularHtmlLink && !noBrokenLinkCheck) {
-        linksCollector.collectLink(targetLink);
+    // See also RR logic:
+    // 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;
+    if (!noBrokenLinkCheck && (isAnchorLink || !isRegularHtmlLink)) {
+        brokenLinks.collectLink(targetLink);
+    }
+    if (props.id) {
+        brokenLinks.collectAnchor(props.id);
     }
     return isRegularHtmlLink ? (
     // eslint-disable-next-line jsx-a11y/anchor-has-content, @docusaurus/no-html-links

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

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+/// <reference types="@docusaurus/module-type-aliases" />
+import type { BrokenLinks } from '@docusaurus/useBrokenLinks';
+export default function useBrokenLinks(): BrokenLinks;

package/lib/client/exports/useBrokenLinks.js

@@ -0,0 +1,10 @@
+/**
+ * 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 { useBrokenLinksContext } from '../BrokenLinksContext';
+export default function useBrokenLinks() {
+    return useBrokenLinksContext();
+}

package/lib/client/serverEntry.js

@@ -18,7 +18,7 @@ import { minify } from 'html-minifier-terser';
 import { renderStaticApp } from './serverRenderer';
 import preload from './preload';
 import App from './App';
-import { createStatefulLinksCollector, LinksCollectorProvider, } from './LinksCollector';
+import { createStatefulBrokenLinks, BrokenLinksProvider, } from './BrokenLinksContext';
 const getCompiledSSRTemplate = _.memoize((template) => eta.compile(template.trim(), {
     rmWhitespace: true,
 }));
@@ -61,20 +61,24 @@ async function doRender(locals) {
     const modules = new Set();
     const routerContext = {};
     const helmetContext = {};
-    const linksCollector = createStatefulLinksCollector();
+    const statefulBrokenLinks = createStatefulBrokenLinks();
     const app = (
     // @ts-expect-error: we are migrating away from react-loadable anyways
     <Loadable.Capture report={(moduleName) => modules.add(moduleName)}>
       <HelmetProvider context={helmetContext}>
         <StaticRouter location={location} context={routerContext}>
-          <LinksCollectorProvider linksCollector={linksCollector}>
+          <BrokenLinksProvider brokenLinks={statefulBrokenLinks}>
             <App />
-          </LinksCollectorProvider>
+          </BrokenLinksProvider>
         </StaticRouter>
       </HelmetProvider>
     </Loadable.Capture>);
     const appHtml = await renderStaticApp(app);
-    onLinksCollected(location, linksCollector.getCollectedLinks());
+    onLinksCollected({
+        staticPagePath: location,
+        anchors: statefulBrokenLinks.getCollectedAnchors(),
+        links: statefulBrokenLinks.getCollectedLinks(),
+    });
     const { helmet } = helmetContext;
     const htmlAttributes = helmet.htmlAttributes.toString();
     const bodyAttributes = helmet.bodyAttributes.toString();

package/lib/commands/build.js

@@ -100,7 +100,7 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
         localizePath: cliOptions.locale ? false : undefined,
     });
     // Apply user webpack config.
-    const { outDir, generatedFilesDir, plugins, siteConfig: { baseUrl, onBrokenLinks, staticDirectories: staticDirectoriesOption, }, routes, } = props;
+    const { outDir, generatedFilesDir, plugins, siteConfig: { onBrokenLinks, onBrokenAnchors, staticDirectories: staticDirectoriesOption, }, routes, } = props;
     const clientManifestPath = path_1.default.join(generatedFilesDir, 'client-manifest.json');
     let clientConfig = (0, webpack_merge_1.default)(await (0, client_1.default)(props, cliOptions.minify, true), {
         plugins: [
@@ -115,12 +115,12 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
             }),
         ].filter((x) => Boolean(x)),
     });
-    const allCollectedLinks = {};
+    const collectedLinks = {};
     const headTags = {};
     let serverConfig = await (0, server_2.default)({
         props,
-        onLinksCollected: (staticPagePath, links) => {
-            allCollectedLinks[staticPagePath] = links;
+        onLinksCollected: ({ staticPagePath, links, anchors }) => {
+            collectedLinks[staticPagePath] = { links, anchors };
         },
         onHeadTagsCollected: (staticPagePath, tags) => {
             headTags[staticPagePath] = tags;
@@ -190,11 +190,10 @@ async function buildLocale({ siteDir, locale, cliOptions, forceTerminate, isLast
         });
     }));
     await (0, brokenLinks_1.handleBrokenLinks)({
-        allCollectedLinks,
+        collectedLinks,
         routes,
         onBrokenLinks,
-        outDir,
-        baseUrl,
+        onBrokenAnchors,
     });
     logger_1.default.success `Generated static files in path=${path_1.default.relative(process.cwd(), outDir)}.`;
     if (isLastLocale) {

package/lib/server/brokenLinks.d.ts

@@ -5,12 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 import type { RouteConfig, ReportingSeverity } from '@docusaurus/types';
-export declare function handleBrokenLinks({ allCollectedLinks, onBrokenLinks, routes, baseUrl, outDir, }: {
-    allCollectedLinks: {
-        [location: string]: string[];
+type CollectedLinks = {
+    [pathname: string]: {
+        links: string[];
+        anchors: string[];
     };
+};
+export declare function handleBrokenLinks({ collectedLinks, onBrokenLinks, onBrokenAnchors, routes, }: {
+    collectedLinks: CollectedLinks;
     onBrokenLinks: ReportingSeverity;
+    onBrokenAnchors: ReportingSeverity;
     routes: RouteConfig[];
-    baseUrl: string;
-    outDir: string;
 }): Promise<void>;
+export {};

package/lib/server/brokenLinks.js

@@ -8,36 +8,116 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.handleBrokenLinks = void 0;
 const tslib_1 = require("tslib");
-const fs_extra_1 = tslib_1.__importDefault(require("fs-extra"));
-const path_1 = tslib_1.__importDefault(require("path"));
 const lodash_1 = tslib_1.__importDefault(require("lodash"));
 const logger_1 = tslib_1.__importDefault(require("@docusaurus/logger"));
-const combine_promises_1 = tslib_1.__importDefault(require("combine-promises"));
 const react_router_config_1 = require("react-router-config");
 const utils_1 = require("@docusaurus/utils");
 const utils_2 = require("./utils");
-// matchRoutes does not support qs/anchors, so we remove it!
-function onlyPathname(link) {
-    return link.split('#')[0].split('?')[0];
+function matchRoutes(routeConfig, pathname) {
+    // @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.
+    return (0, react_router_config_1.matchRoutes)(routeConfig, pathname);
 }
-function getPageBrokenLinks({ pagePath, pageLinks, routes, }) {
-    // 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 = (0, utils_1.resolvePathname)(onlyPathname(link), pagePath);
-        return { link, resolvedLink };
+function createBrokenLinksHelper({ collectedLinks, routes, }) {
+    const validPathnames = new Set(collectedLinks.keys());
+    // IMPORTANT: this is an optimization
+    // See https://github.com/facebook/docusaurus/issues/9754
+    // Matching against the route array can be expensive
+    // If the route is already in the valid pathnames,
+    // we can avoid matching against it
+    const remainingRoutes = (function filterRoutes() {
+        // Goal: unit tests should behave the same with this enabled or disabled
+        const disableOptimization = false;
+        if (disableOptimization) {
+            return routes;
+        }
+        // We must consider the "exact" and "strict" match attribute
+        // We can only infer pre-validated pathnames from a route from exact routes
+        const [validPathnameRoutes, otherRoutes] = lodash_1.default.partition(routes, (route) => route.exact && validPathnames.has(route.path));
+        // If a route is non-strict (non-sensitive to trailing slashes)
+        // We must pre-validate all possible paths
+        validPathnameRoutes.forEach((validPathnameRoute) => {
+            if (!validPathnameRoute.strict) {
+                validPathnames.add((0, utils_1.addTrailingSlash)(validPathnameRoute.path));
+                validPathnames.add((0, utils_1.removeTrailingSlash)(validPathnameRoute.path));
+            }
+        });
+        return otherRoutes;
+    })();
+    function isPathnameMatchingAnyRoute(pathname) {
+        if (matchRoutes(remainingRoutes, pathname).length > 0) {
+            // IMPORTANT: this is an optimization
+            // See https://github.com/facebook/docusaurus/issues/9754
+            // Large Docusaurus sites have many routes!
+            // We try to minimize calls to a possibly expensive matchRoutes function
+            validPathnames.add(pathname);
+            return true;
+        }
+        return false;
+    }
+    function isPathBrokenLink(linkPath) {
+        const pathnames = [linkPath.pathname, decodeURI(linkPath.pathname)];
+        if (pathnames.some((p) => validPathnames.has(p))) {
+            return false;
+        }
+        if (pathnames.some(isPathnameMatchingAnyRoute)) {
+            return false;
+        }
+        return true;
     }
-    function isBrokenLink(link) {
-        const matchedRoutes = [link, decodeURI(link)]
-            // @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;
+    function isAnchorBrokenLink(linkPath) {
+        const { pathname, hash } = linkPath;
+        // Link has no hash: it can't be a broken anchor link
+        if (hash === undefined) {
+            return false;
+        }
+        // Link has empty hash ("#", "/page#"...): we do not report it as broken
+        // Empty hashes are used for various weird reasons, by us and other users...
+        // See for example: https://github.com/facebook/docusaurus/pull/6003
+        if (hash === '') {
+            return false;
+        }
+        const targetPage = collectedLinks.get(pathname) || collectedLinks.get(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) {
+            return true;
+        }
+        // it's a not broken anchor if the anchor exists on the target page
+        if (targetPage.anchors.has(hash) ||
+            targetPage.anchors.has(decodeURIComponent(hash))) {
+            return false;
+        }
+        return true;
     }
-    return pageLinks.map(resolveLink).filter((l) => isBrokenLink(l.resolvedLink));
+    return {
+        collectedLinks,
+        isPathBrokenLink,
+        isAnchorBrokenLink,
+    };
+}
+function getBrokenLinksForPage({ pagePath, helper, }) {
+    const pageData = helper.collectedLinks.get(pagePath);
+    const brokenLinks = [];
+    pageData.links.forEach((link) => {
+        const linkPath = (0, utils_1.parseURLPath)(link, pagePath);
+        if (helper.isPathBrokenLink(linkPath)) {
+            brokenLinks.push({
+                link,
+                resolvedLink: (0, utils_1.serializeURLPath)(linkPath),
+                anchor: false,
+            });
+        }
+        else if (helper.isAnchorBrokenLink(linkPath)) {
+            brokenLinks.push({
+                link,
+                resolvedLink: (0, utils_1.serializeURLPath)(linkPath),
+                anchor: true,
+            });
+        }
+    });
+    return brokenLinks;
 }
 /**
  * The route defs can be recursive, and have a parent match-all route. We don't
@@ -49,25 +129,60 @@ function filterIntermediateRoutes(routesInput) {
     const routesWithout404 = routesInput.filter((route) => route.path !== '*');
     return (0, utils_2.getAllFinalRoutes)(routesWithout404);
 }
-function getAllBrokenLinks({ allCollectedLinks, routes, }) {
+function getBrokenLinks({ collectedLinks, routes, }) {
     const filteredRoutes = filterIntermediateRoutes(routes);
-    const allBrokenLinks = lodash_1.default.mapValues(allCollectedLinks, (pageLinks, pagePath) => getPageBrokenLinks({ pageLinks, pagePath, routes: filteredRoutes }));
-    return lodash_1.default.pickBy(allBrokenLinks, (brokenLinks) => brokenLinks.length > 0);
+    const helper = createBrokenLinksHelper({
+        collectedLinks,
+        routes: filteredRoutes,
+    });
+    const result = {};
+    collectedLinks.forEach((_unused, pagePath) => {
+        try {
+            result[pagePath] = getBrokenLinksForPage({
+                pagePath,
+                helper,
+            });
+        }
+        catch (e) {
+            throw new Error(`Unable to get broken links for page ${pagePath}.`, {
+                cause: e,
+            });
+        }
+    });
+    return result;
 }
-function getBrokenLinksErrorMessage(allBrokenLinks) {
-    if (Object.keys(allBrokenLinks).length === 0) {
-        return undefined;
-    }
-    function brokenLinkMessage(brokenLink) {
-        const showResolvedLink = brokenLink.link !== brokenLink.resolvedLink;
-        return `${brokenLink.link}${showResolvedLink ? ` (resolved as: ${brokenLink.resolvedLink})` : ''}`;
-    }
-    function pageBrokenLinksMessage(pagePath, brokenLinks) {
-        return `
-- On source page path = ${pagePath}:
+function brokenLinkMessage(brokenLink) {
+    const showResolvedLink = brokenLink.link !== brokenLink.resolvedLink;
+    return `${brokenLink.link}${showResolvedLink ? ` (resolved as: ${brokenLink.resolvedLink})` : ''}`;
+}
+function createBrokenLinksMessage(pagePath, brokenLinks) {
+    const type = brokenLinks[0]?.anchor === true ? 'anchor' : 'link';
+    const anchorMessage = brokenLinks.length > 0
+        ? `- Broken ${type} on source page path = ${pagePath}:
    -> linking to ${brokenLinks
             .map(brokenLinkMessage)
-            .join('\n   -> linking to ')}`;
+            .join('\n   -> linking to ')}`
+        : '';
+    return `${anchorMessage}`;
+}
+function createBrokenAnchorsMessage(brokenAnchors) {
+    if (Object.keys(brokenAnchors).length === 0) {
+        return undefined;
+    }
+    return `Docusaurus found broken anchors!
+
+Please check the pages of your site in the list below, and make sure you don't reference any anchor that does not exist.
+Note: it's possible to ignore broken anchors with the 'onBrokenAnchors' Docusaurus configuration, and let the build pass.
+
+Exhaustive list of all broken anchors found:
+${Object.entries(brokenAnchors)
+        .map(([pagePath, brokenLinks]) => createBrokenLinksMessage(pagePath, brokenLinks))
+        .join('\n')}
+`;
+}
+function createBrokenPathsMessage(brokenPathsMap) {
+    if (Object.keys(brokenPathsMap).length === 0) {
+        return undefined;
     }
     /**
      * If there's a broken link appearing very often, it is probably a broken link
@@ -75,7 +190,7 @@ function getBrokenLinksErrorMessage(allBrokenLinks) {
      * this out. See https://github.com/facebook/docusaurus/issues/3567#issuecomment-706973805
      */
     function getLayoutBrokenLinksHelpMessage() {
-        const flatList = Object.entries(allBrokenLinks).flatMap(([pagePage, brokenLinks]) => brokenLinks.map((brokenLink) => ({ pagePage, brokenLink })));
+        const flatList = Object.entries(brokenPathsMap).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)
@@ -97,60 +212,65 @@ Please check the pages of your site in the list below, and make sure you don't r
 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))
+${Object.entries(brokenPathsMap)
+        .map(([pagePath, brokenPaths]) => createBrokenLinksMessage(pagePath, brokenPaths))
         .join('\n')}
 `;
 }
-async function isExistingFile(filePath) {
-    try {
-        return (await fs_extra_1.default.stat(filePath)).isFile();
-    }
-    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, }) {
-    async function linkFileExists(link) {
-        // /baseUrl/javadoc/ -> /outDir/javadoc
-        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`, path_1.default.join(baseFilePath, 'index.html'));
+function splitBrokenLinks(brokenLinks) {
+    const brokenPaths = {};
+    const brokenAnchors = {};
+    Object.entries(brokenLinks).forEach(([pathname, pageBrokenLinks]) => {
+        const [anchorBrokenLinks, pathBrokenLinks] = lodash_1.default.partition(pageBrokenLinks, (link) => link.anchor);
+        if (pathBrokenLinks.length > 0) {
+            brokenPaths[pathname] = pathBrokenLinks;
         }
-        for (const file of filePathsToTry) {
-            if (await isExistingFile(file)) {
-                return true;
-            }
+        if (anchorBrokenLinks.length > 0) {
+            brokenAnchors[pathname] = anchorBrokenLinks;
         }
-        return false;
+    });
+    return { brokenPaths, brokenAnchors };
+}
+function reportBrokenLinks({ brokenLinks, onBrokenLinks, onBrokenAnchors, }) {
+    // We need to split the broken links reporting in 2 for better granularity
+    // This is because we need to report broken path/anchors independently
+    // For v3.x retro-compatibility, we can't throw by default for broken anchors
+    // TODO Docusaurus v4: make onBrokenAnchors throw by default?
+    const { brokenPaths, brokenAnchors } = splitBrokenLinks(brokenLinks);
+    const pathErrorMessage = createBrokenPathsMessage(brokenPaths);
+    if (pathErrorMessage) {
+        logger_1.default.report(onBrokenLinks)(pathErrorMessage);
     }
-    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)));
+    const anchorErrorMessage = createBrokenAnchorsMessage(brokenAnchors);
+    if (anchorErrorMessage) {
+        logger_1.default.report(onBrokenAnchors)(anchorErrorMessage);
+    }
+}
+// Users might use the useBrokenLinks() API in weird unexpected ways
+// JS users might call "collectLink(undefined)" for example
+// TS users might call "collectAnchor('#hash')" with/without #
+// We clean/normalize the collected data to avoid obscure errors being thrown
+// We also use optimized data structures for a faster algorithm
+function normalizeCollectedLinks(collectedLinks) {
+    const result = new Map();
+    Object.entries(collectedLinks).forEach(([pathname, pageCollectedData]) => {
+        result.set(pathname, {
+            links: new Set(pageCollectedData.links.filter(lodash_1.default.isString)),
+            anchors: new Set(pageCollectedData.anchors
+                .filter(lodash_1.default.isString)
+                .map((anchor) => (anchor.startsWith('#') ? anchor.slice(1) : anchor))),
+        });
+    });
+    return result;
 }
-async function handleBrokenLinks({ allCollectedLinks, onBrokenLinks, routes, baseUrl, outDir, }) {
-    if (onBrokenLinks === 'ignore') {
+async function handleBrokenLinks({ collectedLinks, onBrokenLinks, onBrokenAnchors, routes, }) {
+    if (onBrokenLinks === 'ignore' && onBrokenAnchors === '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...
-    const allCollectedLinksFiltered = await filterExistingFileLinks({
-        allCollectedLinks,
-        baseUrl,
-        outDir,
-    });
-    const allBrokenLinks = getAllBrokenLinks({
-        allCollectedLinks: allCollectedLinksFiltered,
+    const brokenLinks = getBrokenLinks({
         routes,
+        collectedLinks: normalizeCollectedLinks(collectedLinks),
     });
-    const errorMessage = getBrokenLinksErrorMessage(allBrokenLinks);
-    if (errorMessage) {
-        logger_1.default.report(onBrokenLinks)(errorMessage);
-    }
+    reportBrokenLinks({ brokenLinks, onBrokenLinks, onBrokenAnchors });
 }
 exports.handleBrokenLinks = handleBrokenLinks;

package/lib/server/configValidation.d.ts

@@ -5,8 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { Joi } from '@docusaurus/utils-validation';
-import type { DocusaurusConfig, I18nConfig } from '@docusaurus/types';
+import type { DocusaurusConfig, I18nConfig, MarkdownConfig } from '@docusaurus/types';
 export declare const DEFAULT_I18N_CONFIG: I18nConfig;
-export declare const DEFAULT_CONFIG: Pick<DocusaurusConfig, 'i18n' | 'onBrokenLinks' | 'onBrokenMarkdownLinks' | 'onDuplicateRoutes' | 'plugins' | 'themes' | 'presets' | 'headTags' | 'stylesheets' | 'scripts' | 'clientModules' | 'customFields' | 'themeConfig' | 'titleDelimiter' | 'noIndex' | 'tagline' | 'baseUrlIssueBanner' | 'staticDirectories' | 'markdown'>;
+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 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_I18N_CONFIG = void 0;
+exports.validateConfig = exports.ConfigSchema = exports.DEFAULT_CONFIG = exports.DEFAULT_MARKDOWN_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';
@@ -16,9 +16,22 @@ exports.DEFAULT_I18N_CONFIG = {
     locales: [DEFAULT_I18N_LOCALE],
     localeConfigs: {},
 };
+exports.DEFAULT_MARKDOWN_CONFIG = {
+    format: 'mdx',
+    mermaid: false,
+    preprocessor: undefined,
+    parseFrontMatter: utils_1.DEFAULT_PARSE_FRONT_MATTER,
+    mdx1Compat: {
+        comments: true,
+        admonitions: true,
+        headingIds: true,
+    },
+    remarkRehypeOptions: undefined,
+};
 exports.DEFAULT_CONFIG = {
     i18n: exports.DEFAULT_I18N_CONFIG,
     onBrokenLinks: 'throw',
+    onBrokenAnchors: 'warn',
     onBrokenMarkdownLinks: 'warn',
     onDuplicateRoutes: 'warn',
     plugins: [],
@@ -35,25 +48,15 @@ exports.DEFAULT_CONFIG = {
     tagline: '',
     baseUrlIssueBanner: true,
     staticDirectories: [utils_1.DEFAULT_STATIC_DIR_NAME],
-    markdown: {
-        format: 'mdx',
-        mermaid: false,
-        preprocessor: undefined,
-        mdx1Compat: {
-            comments: true,
-            admonitions: true,
-            headingIds: true,
-        },
-    },
+    markdown: exports.DEFAULT_MARKDOWN_CONFIG,
 };
 function createPluginSchema(theme) {
-    return (utils_validation_1.Joi.alternatives()
+    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
@@ -82,7 +85,7 @@ ${validConfigExample}
 `;
         });
         return errors;
-    }));
+    });
 }
 const PluginSchema = createPluginSchema(false);
 const ThemeSchema = createPluginSchema(true);
@@ -147,6 +150,9 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
     onBrokenLinks: utils_validation_1.Joi.string()
         .equal('ignore', 'log', 'warn', 'throw')
         .default(exports.DEFAULT_CONFIG.onBrokenLinks),
+    onBrokenAnchors: utils_validation_1.Joi.string()
+        .equal('ignore', 'log', 'warn', 'throw')
+        .default(exports.DEFAULT_CONFIG.onBrokenAnchors),
     onBrokenMarkdownLinks: utils_validation_1.Joi.string()
         .equal('ignore', 'log', 'warn', 'throw')
         .default(exports.DEFAULT_CONFIG.onBrokenMarkdownLinks),
@@ -214,6 +220,7 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
         format: utils_validation_1.Joi.string()
             .equal('mdx', 'md', 'detect')
             .default(exports.DEFAULT_CONFIG.markdown.format),
+        parseFrontMatter: utils_validation_1.Joi.function().default(() => exports.DEFAULT_CONFIG.markdown.parseFrontMatter),
         mermaid: utils_validation_1.Joi.boolean().default(exports.DEFAULT_CONFIG.markdown.mermaid),
         preprocessor: utils_validation_1.Joi.function()
             .arity(1)
@@ -224,6 +231,11 @@ exports.ConfigSchema = utils_validation_1.Joi.object({
             admonitions: utils_validation_1.Joi.boolean().default(exports.DEFAULT_CONFIG.markdown.mdx1Compat.admonitions),
             headingIds: utils_validation_1.Joi.boolean().default(exports.DEFAULT_CONFIG.markdown.mdx1Compat.headingIds),
         }).default(exports.DEFAULT_CONFIG.markdown.mdx1Compat),
+        remarkRehypeOptions: 
+        // add proper external options validation?
+        // Not sure if it's a good idea, validation is likely to become stale
+        // See https://github.com/remarkjs/remark-rehype#options
+        utils_validation_1.Joi.object().unknown(),
     }).default(exports.DEFAULT_CONFIG.markdown),
 }).messages({
     'docusaurus.configValidationWarning': 'Docusaurus config validation warning. Field {#label}: {#warningMessage}',

package/lib/server/getHostPort.js

@@ -40,7 +40,10 @@ function getProcessForPort(port) {
  */
 async function choosePort(host, defaultPort) {
     try {
-        const port = await (0, detect_port_1.default)({ port: defaultPort, hostname: host });
+        const port = await (0, detect_port_1.default)({
+            port: defaultPort,
+            ...(host !== 'localhost' && { hostname: host }),
+        });
         if (port === defaultPort) {
             return port;
         }

package/lib/server/routes.js

@@ -159,6 +159,14 @@ ${JSON.stringify(routeConfig)}`);
         props,
     });
 }
+/**
+ * Old stuff
+ * As far as I understand, this is what permits to SSG the 404.html file
+ * This is rendered through the catch-all ComponentCreator("*") route
+ * Note CDNs only understand the 404.html file by convention
+ * The extension probably permits to avoid emitting "/404/index.html"
+ */
+const NotFoundRoutePath = '/404.html';
 /**
  * Routes are prepared into three temp files:
  *
@@ -175,7 +183,7 @@ function loadRoutes(routeConfigs, baseUrl, onDuplicateRoutes) {
         routesConfig: '',
         routesChunkNames: {},
         registry: {},
-        routesPaths: [(0, utils_1.normalizeUrl)([baseUrl, '404.html'])],
+        routesPaths: [(0, utils_1.normalizeUrl)([baseUrl, NotFoundRoutePath])],
     };
     // `genRouteCode` would mutate `res`
     const routeConfigSerialized = routeConfigs

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "3.0.1",
+  "version": "3.1.1",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -43,13 +43,13 @@
     "@babel/runtime": "^7.22.6",
     "@babel/runtime-corejs3": "^7.22.6",
     "@babel/traverse": "^7.22.8",
-    "@docusaurus/cssnano-preset": "3.0.1",
-    "@docusaurus/logger": "3.0.1",
-    "@docusaurus/mdx-loader": "3.0.1",
+    "@docusaurus/cssnano-preset": "3.1.1",
+    "@docusaurus/logger": "3.1.1",
+    "@docusaurus/mdx-loader": "3.1.1",
     "@docusaurus/react-loadable": "5.5.2",
-    "@docusaurus/utils": "3.0.1",
-    "@docusaurus/utils-common": "3.0.1",
-    "@docusaurus/utils-validation": "3.0.1",
+    "@docusaurus/utils": "3.1.1",
+    "@docusaurus/utils-common": "3.1.1",
+    "@docusaurus/utils-validation": "3.1.1",
     "@slorber/static-site-generator-webpack-plugin": "^4.0.7",
     "@svgr/webpack": "^6.5.1",
     "autoprefixer": "^10.4.14",
@@ -104,8 +104,8 @@
     "webpackbar": "^5.0.2"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "3.0.1",
-    "@docusaurus/types": "3.0.1",
+    "@docusaurus/module-type-aliases": "3.1.1",
+    "@docusaurus/types": "3.1.1",
     "@types/detect-port": "^1.3.3",
     "@types/react-dom": "^18.2.7",
     "@types/react-router-config": "^5.0.7",
@@ -124,5 +124,5 @@
   "engines": {
     "node": ">=18.0"
   },
-  "gitHead": "29d816067fd0022d4ca3bd5fdc42098dac9f7ffc"
+  "gitHead": "8017f6a6776ba1bd7065e630a52fe2c2654e2f1b"
 }

package/lib/client/LinksCollector.d.ts

@@ -1,20 +0,0 @@
-/**
- * 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 ReactNode } from 'react';
-type LinksCollector = {
-    collectLink: (link: string) => void;
-};
-type StatefulLinksCollector = LinksCollector & {
-    getCollectedLinks: () => string[];
-};
-export declare const createStatefulLinksCollector: () => StatefulLinksCollector;
-export declare const useLinksCollector: () => LinksCollector;
-export declare function LinksCollectorProvider({ children, linksCollector, }: {
-    children: ReactNode;
-    linksCollector: LinksCollector;
-}): JSX.Element;
-export {};

package/lib/client/LinksCollector.js

@@ -1,26 +0,0 @@
-/**
- * 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 React, { useContext } from 'react';
-export const createStatefulLinksCollector = () => {
-    // Set to dedup, as it's not useful to collect multiple times the same link
-    const allLinks = new Set();
-    return {
-        collectLink: (link) => {
-            allLinks.add(link);
-        },
-        getCollectedLinks: () => [...allLinks],
-    };
-};
-const Context = React.createContext({
-    collectLink: () => {
-        // No-op for client. We only use the broken links checker server-side.
-    },
-});
-export const useLinksCollector = () => useContext(Context);
-export function LinksCollectorProvider({ children, linksCollector, }) {
-    return <Context.Provider value={linksCollector}>{children}</Context.Provider>;
-}