@docusaurus/core 3.0.1 → 3.1.0

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/{LinksCollector.js → BrokenLinksContext.js}

@@ -5,22 +5,30 @@
  * 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
+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) => {
+            allAnchors.add(anchor);
+        },
         collectLink: (link) => {
             allLinks.add(link);
         },
+        getCollectedAnchors: () => [...allAnchors],
         getCollectedLinks: () => [...allLinks],
     };
 };
 const Context = React.createContext({
+    collectAnchor: () => {
+        // No-op for client
+    },
     collectLink: () => {
-        // No-op for client. We only use the broken links checker server-side.
+        // No-op for client
     },
 });
-export const useLinksCollector = () => useContext(Context);
-export function LinksCollectorProvider({ children, linksCollector, }) {
-    return <Context.Provider value={linksCollector}>{children}</Context.Provider>;
+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
@@ -100,7 +100,7 @@ function Link({ isNavLink, to, href, activeClassName, isActive, 'data-noBrokenLi
     const isAnchorLink = targetLink?.startsWith('#') ?? false;
     const isRegularHtmlLink = !targetLink || !isInternal || isAnchorLink;
     if (!isRegularHtmlLink && !noBrokenLinkCheck) {
-        linksCollector.collectLink(targetLink);
+        brokenLinks.collectLink(targetLink);
     }
     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,28 +8,15 @@
 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 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 isBrokenLink(link) {
-        const matchedRoutes = [link, decodeURI(link)]
+function getBrokenLinksForPage({ collectedLinks, pagePath, pageLinks, routes, }) {
+    // console.log('routes:', routes);
+    function isPathBrokenLink(linkPath) {
+        const matchedRoutes = [linkPath.pathname, decodeURI(linkPath.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.
@@ -37,7 +24,45 @@ function getPageBrokenLinks({ pagePath, pageLinks, routes, }) {
             .flat();
         return matchedRoutes.length === 0;
     }
-    return pageLinks.map(resolveLink).filter((l) => isBrokenLink(l.resolvedLink));
+    function isAnchorBrokenLink(linkPath) {
+        const { pathname, hash } = linkPath;
+        // Link has no hash: it can't be a broken anchor link
+        if (hash === undefined) {
+            return false;
+        }
+        const targetPage = collectedLinks[pathname] || collectedLinks[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 broken anchor if the target page exists
+        // but the anchor does not exist on that page
+        return !targetPage.anchors.includes(hash);
+    }
+    const brokenLinks = pageLinks.flatMap((link) => {
+        const linkPath = (0, utils_1.parseURLPath)(link, pagePath);
+        if (isPathBrokenLink(linkPath)) {
+            return [
+                {
+                    link,
+                    resolvedLink: (0, utils_1.serializeURLPath)(linkPath),
+                    anchor: false,
+                },
+            ];
+        }
+        if (isAnchorBrokenLink(linkPath)) {
+            return [
+                {
+                    link,
+                    resolvedLink: (0, utils_1.serializeURLPath)(linkPath),
+                    anchor: true,
+                },
+            ];
+        }
+        return [];
+    });
+    return brokenLinks;
 }
 /**
  * The route defs can be recursive, and have a parent match-all route. We don't
@@ -49,25 +74,48 @@ 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);
+    return lodash_1.default.mapValues(collectedLinks, (pageCollectedData, pagePath) => getBrokenLinksForPage({
+        collectedLinks,
+        pageLinks: pageCollectedData.links,
+        pageAnchors: pageCollectedData.anchors,
+        pagePath,
+        routes: filteredRoutes,
+    }));
 }
-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 +123,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 +145,45 @@ 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);
+    }
+    const anchorErrorMessage = createBrokenAnchorsMessage(brokenAnchors);
+    if (anchorErrorMessage) {
+        logger_1.default.report(onBrokenAnchors)(anchorErrorMessage);
     }
-    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)));
 }
-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,
-        routes,
-    });
-    const errorMessage = getBrokenLinksErrorMessage(allBrokenLinks);
-    if (errorMessage) {
-        logger_1.default.report(onBrokenLinks)(errorMessage);
-    }
+    const brokenLinks = getBrokenLinks({ routes, collectedLinks });
+    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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@docusaurus/core",
   "description": "Easy to Maintain Open Source Documentation Websites",
-  "version": "3.0.1",
+  "version": "3.1.0",
   "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.0",
+    "@docusaurus/logger": "3.1.0",
+    "@docusaurus/mdx-loader": "3.1.0",
     "@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.0",
+    "@docusaurus/utils-common": "3.1.0",
+    "@docusaurus/utils-validation": "3.1.0",
     "@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.0",
+    "@docusaurus/types": "3.1.0",
     "@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": "a5e675821f0e8b70b591fcebf19fd60a70d55548"
 }

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 {};