feat(core): make broken link checker detect broken anchors - add onBrokenAnchors config

packages/docusaurus-mdx-loader/src/remark/transformLinks/__tests__/__snapshots__/index.test.ts.snap

@@ -12,17 +12,17 @@ exports[`transformAsset plugin pathname protocol 1`] = `
 exports[`transformAsset plugin transform md links to <a /> 1`] = `
 "[asset](https://example.com/asset.pdf)
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} />
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} />
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
 
-in paragraph <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
+in paragraph <a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset (2).pdf").default}>asset with URL encoded chars</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset (2).pdf").default}>asset with URL encoded chars</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default + '#page=2'}>asset with hash</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default + '#page=2'}>asset with hash</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} title="Title">asset</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default} title="Title">asset</a>
 
 [page](noUrl.md)
 
@@ -36,24 +36,24 @@ in paragraph <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file
 
 [assets](/github/!file-loader!/assets.pdf)
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}>asset</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static2/asset2.pdf").default}>asset2</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static2/asset2.pdf").default}>asset2</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>staticAsset.pdf</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>staticAsset.pdf</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>@site/static/staticAsset.pdf</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>@site/static/staticAsset.pdf</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default + '#page=2'} title="Title">@site/static/staticAsset.pdf</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default + '#page=2'} title="Title">@site/static/staticAsset.pdf</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>Just staticAsset.pdf</a>, and <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>**awesome** staticAsset 2.pdf 'It is really "AWESOME"'</a>, but also <a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>coded \`staticAsset 3.pdf\`</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>Just staticAsset.pdf</a>, and <a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>**awesome** staticAsset 2.pdf 'It is really "AWESOME"'</a>, but also <a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAsset.pdf").default}>coded \`staticAsset 3.pdf\`</a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAssetImage.png").default}><img alt="Clickable Docusaurus logo" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/staticAssetImage.png").default} width="200" height="200" /></a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/staticAssetImage.png").default}><img alt="Clickable Docusaurus logo" src={require("!<PROJECT_ROOT>/node_modules/url-loader/dist/cjs.js?limit=10000&name=assets/images/[name]-[contenthash].[ext]&fallback=<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js!./static/staticAssetImage.png").default} width="200" height="200" /></a>
 
-<a target="_blank" href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}><span style={{color: "red"}}>Stylized link to asset file</span></a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./asset.pdf").default}><span style={{color: "red"}}>Stylized link to asset file</span></a>
 
-<a target="_blank" href={require("./data.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./data.json").default}>JSON</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("./data.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./data.json").default}>JSON</a>
 
-<a target="_blank" href={require("./static/static-json.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/static-json.json").default}>static JSON</a>
+<a target="_blank" data-noBrokenLinkCheck={true} href={require("./static/static-json.raw!=!<PROJECT_ROOT>/node_modules/file-loader/dist/cjs.js?name=assets/files/[name]-[contenthash].[ext]!./static/static-json.json").default}>static JSON</a>
 "
 `;

packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts

@@ -73,6 +73,34 @@ async function toAssetRequireNode(
     value: '_blank',
   });
 
+  // Assets are not routes, and are required by Webpack already
+  // They should not trigger the broken link checker
+  attributes.push({
+    type: 'mdxJsxAttribute',
+    name: 'data-noBrokenLinkCheck',
+    value: {
+      type: 'mdxJsxAttributeValueExpression',
+      value: 'true',
+      data: {
+        estree: {
+          type: 'Program',
+          body: [
+            {
+              type: 'ExpressionStatement',
+              expression: {
+                type: 'Literal',
+                value: true,
+                raw: 'true',
+              },
+            },
+          ],
+          sourceType: 'module',
+          comments: [],
+        },
+      },
+    },
+  });
+
   attributes.push({
     type: 'mdxJsxAttribute',
     name: 'href',

packages/docusaurus-module-type-aliases/src/index.d.ts

@@ -260,6 +260,15 @@ declare module '@docusaurus/useRouteContext' {
   export default function useRouteContext(): PluginRouteContext;
 }
 
+declare module '@docusaurus/useBrokenLinks' {
+  export type BrokenLinks = {
+    collectLink: (link: string) => void;
+    collectAnchor: (anchor: string) => void;
+  };
+
+  export default function useBrokenLinks(): BrokenLinks;
+}
+
 declare module '@docusaurus/useIsBrowser' {
   export default function useIsBrowser(): boolean;
 }

packages/docusaurus-theme-classic/src/theme/Heading/index.tsx

@@ -10,11 +10,13 @@ import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
+import useBrokenLinks from '@docusaurus/useBrokenLinks';
 import type {Props} from '@theme/Heading';
 
 import styles from './styles.module.css';
 
 export default function Heading({as: As, id, ...props}: Props): JSX.Element {
+  const brokenLinks = useBrokenLinks();
   const {
     navbar: {hideOnScroll},
   } = useThemeConfig();
@@ -23,6 +25,8 @@ export default function Heading({as: As, id, ...props}: Props): JSX.Element {
     return <As {...props} id={undefined} />;
   }
 
+  brokenLinks.collectAnchor(id);
+
   const anchorTitle = translate(
     {
       id: 'theme.common.headingLinkTitle',

packages/docusaurus-types/src/config.d.ts

@@ -143,6 +143,13 @@ export type DocusaurusConfig = {
    * @default "throw"
    */
   onBrokenLinks: ReportingSeverity;
+  /**
+   * The behavior of Docusaurus when it detects any broken link.
+   *
+   * @see // TODO
+   * @default "warn"
+   */
+  onBrokenAnchors: ReportingSeverity;
   /**
    * The behavior of Docusaurus when it detects any broken markdown link.
    *

packages/docusaurus/src/client/BrokenLinksContext.tsx

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

packages/docusaurus/src/client/exports/Link.tsx

@@ -16,7 +16,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';
 import type {Props} from '@docusaurus/Link';
 
@@ -44,7 +44,7 @@ function Link(
     siteConfig: {trailingSlash, baseUrl},
   } = useDocusaurusContext();
   const {withBaseUrl} = useBaseUrlUtils();
-  const linksCollector = useLinksCollector();
+  const brokenLinks = useBrokenLinks();
   const innerRef = useRef<HTMLAnchorElement | null>(null);
 
   useImperativeHandle(forwardedRef, () => innerRef.current!);
@@ -144,7 +144,7 @@ function Link(
   const isRegularHtmlLink = !targetLink || !isInternal || isAnchorLink;
 
   if (!isRegularHtmlLink && !noBrokenLinkCheck) {
-    linksCollector.collectLink(targetLink!);
+    brokenLinks.collectLink(targetLink!);
   }
 
   return isRegularHtmlLink ? (

packages/docusaurus/src/client/exports/useBrokenLinks.ts

@@ -0,0 +1,13 @@
+/**
+ * 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';
+import type {BrokenLinks} from '@docusaurus/useBrokenLinks';
+
+export default function useBrokenLinks(): BrokenLinks {
+  return useBrokenLinksContext();
+}

packages/docusaurus/src/client/serverEntry.tsx

@@ -20,9 +20,9 @@ import {renderStaticApp} from './serverRenderer';
 import preload from './preload';
 import App from './App';
 import {
-  createStatefulLinksCollector,
-  LinksCollectorProvider,
-} from './LinksCollector';
+  createStatefulBrokenLinks,
+  BrokenLinksProvider,
+} from './BrokenLinksContext';
 import type {Locals} from '@slorber/static-site-generator-webpack-plugin';
 
 const getCompiledSSRTemplate = _.memoize((template: string) =>
@@ -96,23 +96,27 @@ async function doRender(locals: Locals & {path: string}) {
   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 as FilledContext;
   const htmlAttributes = helmet.htmlAttributes.toString();

packages/docusaurus/src/commands/build.ts

@@ -110,7 +110,7 @@ export async function build(
     ...i18n.locales.filter((locale) => locale !== i18n.defaultLocale),
   ];
 
-  const results = await mapAsyncSequential(orderedLocales, (locale) => {
+  const results = await mapAsyncSequential(orderedLocales, (locale: any) => {
     const isLastLocale =
       orderedLocales.indexOf(locale) === orderedLocales.length - 1;
     return tryToBuildLocale({locale, isLastLocale});
@@ -152,8 +152,8 @@ async function buildLocale({
     generatedFilesDir,
     plugins,
     siteConfig: {
-      baseUrl,
       onBrokenLinks,
+      onBrokenAnchors,
       staticDirectories: staticDirectoriesOption,
     },
     routes,
@@ -180,13 +180,15 @@ async function buildLocale({
     },
   );
 
-  const allCollectedLinks: {[location: string]: string[]} = {};
+  const allCollectedLinks: {
+    [location: string]: {links: string[]; anchors: string[]};
+  } = {};
   const headTags: {[location: string]: HelmetServerState} = {};
 
   let serverConfig: Configuration = await createServerConfig({
     props,
-    onLinksCollected: (staticPagePath, links) => {
-      allCollectedLinks[staticPagePath] = links;
+    onLinksCollected: ({staticPagePath, links, anchors}) => {
+      allCollectedLinks[staticPagePath] = {links, anchors};
     },
     onHeadTagsCollected: (staticPagePath, tags) => {
       headTags[staticPagePath] = tags;
@@ -291,8 +293,7 @@ async function buildLocale({
     allCollectedLinks,
     routes,
     onBrokenLinks,
-    outDir,
-    baseUrl,
+    onBrokenAnchors,
   });
 
   logger.success`Generated static files in path=${path.relative(

packages/docusaurus/src/deps.d.ts

@@ -42,7 +42,11 @@ declare module '@slorber/static-site-generator-webpack-plugin' {
     headTags: string;
     preBodyTags: string;
     postBodyTags: string;
-    onLinksCollected: (staticPagePath: string, links: string[]) => void;
+    onLinksCollected: (params: {
+      staticPagePath: string;
+      links: string[];
+      anchors: string[];
+    }) => void;
     onHeadTagsCollected: (
       staticPagePath: string,
       tags: HelmetServerState,