fix(core): various broken anchor link fixes (#9732)

Author: slorber

.eslintrc.js

@@ -203,7 +203,10 @@ module.exports = {
       })),
     ],
     'no-template-curly-in-string': WARNING,
-    'no-unused-expressions': [WARNING, {allowTaggedTemplates: true}],
+    'no-unused-expressions': [
+      WARNING,
+      {allowTaggedTemplates: true, allowShortCircuit: true},
+    ],
     'no-useless-escape': WARNING,
     'no-void': [ERROR, {allowAsStatement: true}],
     'prefer-destructuring': WARNING,

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

@@ -262,8 +262,8 @@ declare module '@docusaurus/useRouteContext' {
 
 declare module '@docusaurus/useBrokenLinks' {
   export type BrokenLinks = {
-    collectLink: (link: string) => void;
-    collectAnchor: (anchor: string) => void;
+    collectLink: (link: string | undefined) => void;
+    collectAnchor: (anchor: string | undefined) => void;
   };
 
   export default function useBrokenLinks(): BrokenLinks;

packages/docusaurus-theme-classic/src/theme-classic.d.ts

@@ -867,6 +867,14 @@ declare module '@theme/MDXComponents/Ul' {
   export default function MDXUl(props: Props): JSX.Element;
 }
 
+declare module '@theme/MDXComponents/Li' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'li'> {}
+
+  export default function MDXLi(props: Props): JSX.Element;
+}
+
 declare module '@theme/MDXComponents/Img' {
   import type {ComponentProps} from 'react';
 

packages/docusaurus-theme-classic/src/theme/MDXComponents/Li.tsx

@@ -0,0 +1,17 @@
+/**
+ * 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} from 'react';
+import useBrokenLinks from '@docusaurus/useBrokenLinks';
+import type {Props} from '@theme/MDXComponents/Li';
+
+export default function MDXLi(props: Props): ReactNode | undefined {
+  // MDX Footnotes have ids such as <li id="user-content-fn-1-953011">
+  useBrokenLinks().collectAnchor(props.id);
+
+  return <li {...props} />;
+}

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

@@ -13,6 +13,7 @@ import MDXPre from '@theme/MDXComponents/Pre';
 import MDXDetails from '@theme/MDXComponents/Details';
 import MDXHeading from '@theme/MDXComponents/Heading';
 import MDXUl from '@theme/MDXComponents/Ul';
+import MDXLi from '@theme/MDXComponents/Li';
 import MDXImg from '@theme/MDXComponents/Img';
 import Admonition from '@theme/Admonition';
 import Mermaid from '@theme/Mermaid';
@@ -27,6 +28,7 @@ const MDXComponents: MDXComponentsObject = {
   a: MDXA,
   pre: MDXPre,
   ul: MDXUl,
+  li: MDXLi,
   img: MDXImg,
   h1: (props: ComponentProps<'h1'>) => <MDXHeading as="h1" {...props} />,
   h2: (props: ComponentProps<'h2'>) => <MDXHeading as="h2" {...props} />,

packages/docusaurus-theme-classic/src/theme/NavbarItem/DropdownNavbarItem/index.tsx

@@ -89,6 +89,9 @@ function DropdownNavbarItemDesktop({
         aria-haspopup="true"
         aria-expanded={showDropdown}
         role="button"
+        // # hash permits to make the <a> tag focusable in case no link target
+        // See https://github.com/facebook/docusaurus/pull/6003
+        // There's probably a better solution though...
         href={props.to ? undefined : '#'}
         className={clsx('navbar__link', className)}
         {...props}

packages/docusaurus-theme-common/src/components/Details/index.tsx

@@ -12,6 +12,7 @@ import React, {
   type ReactElement,
 } from 'react';
 import clsx from 'clsx';
+import useBrokenLinks from '@docusaurus/useBrokenLinks';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import {useCollapsible, Collapsible} from '../Collapsible';
 import styles from './styles.module.css';
@@ -47,6 +48,8 @@ export function Details({
   children,
   ...props
 }: DetailsProps): JSX.Element {
+  useBrokenLinks().collectAnchor(props.id);
+
   const isBrowser = useIsBrowser();
   const detailsRef = useRef<HTMLDetailsElement>(null);
 

packages/docusaurus-utils/src/__tests__/urlUtils.test.ts

@@ -301,6 +301,29 @@ describe('parseURLPath', () => {
     });
   });
 
+  it('parse anchor', () => {
+    expect(parseURLPath('#anchor')).toEqual({
+      pathname: '/',
+      search: undefined,
+      hash: 'anchor',
+    });
+    expect(parseURLPath('#anchor', '/page')).toEqual({
+      pathname: '/page',
+      search: undefined,
+      hash: 'anchor',
+    });
+    expect(parseURLPath('#')).toEqual({
+      pathname: '/',
+      search: undefined,
+      hash: '',
+    });
+    expect(parseURLPath('#', '/page')).toEqual({
+      pathname: '/page',
+      search: undefined,
+      hash: '',
+    });
+  });
+
   it('parse hash', () => {
     expect(parseURLPath('/page')).toEqual({
       pathname: '/page',

packages/docusaurus/src/client/BrokenLinksContext.tsx

@@ -18,11 +18,11 @@ export const createStatefulBrokenLinks = (): StatefulBrokenLinks => {
   const allAnchors = new Set<string>();
   const allLinks = new Set<string>();
   return {
-    collectAnchor: (anchor: string): void => {
-      allAnchors.add(anchor);
+    collectAnchor: (anchor: string | undefined): void => {
+      typeof anchor !== 'undefined' && allAnchors.add(anchor);
     },
-    collectLink: (link: string): void => {
-      allLinks.add(link);
+    collectLink: (link: string | undefined): void => {
+      typeof link !== 'undefined' && allLinks.add(link);
     },
     getCollectedAnchors: (): string[] => [...allAnchors],
     getCollectedLinks: (): string[] => [...allLinks],

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

@@ -140,13 +140,20 @@ function Link(
     };
   }, [ioRef, targetLink, IOSupported, isInternal]);
 
+  // It is simple local anchor link targeting current page?
   const isAnchorLink = targetLink?.startsWith('#') ?? false;
+
+  // Should we use a regular <a> tag instead of React-Router Link component?
   const isRegularHtmlLink = !targetLink || !isInternal || isAnchorLink;
 
-  if (!isRegularHtmlLink && !noBrokenLinkCheck) {
+  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
     <a