feat: add eslint plugin no-html-links (#8156)

Co-authored-by: Joshua Chen <sidachen2003@gmail.com>
Co-authored-by: Viktor Malmedal <viktor.malmedal@eniro.com>
Co-authored-by: sebastienlorber <lorber.sebastien@gmail.com>
Co-authored-by: Sébastien Lorber <slorber@users.noreply.github.com>

.eslintrc.js

@@ -374,6 +374,7 @@ module.exports = {
     // locals must be justified with a disable comment.
     '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
     '@typescript-eslint/prefer-optional-chain': ERROR,
+    '@docusaurus/no-html-links': ERROR,
     '@docusaurus/no-untranslated-text': [
       WARNING,
       {

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

@@ -8,22 +8,19 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import {ThemeClassNames} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
 import IconEdit from '@theme/Icon/Edit';
 import type {Props} from '@theme/EditThisPage';
 
 export default function EditThisPage({editUrl}: Props): JSX.Element {
   return (
-    <a
+    <Link to={editUrl} className={ThemeClassNames.common.editThisPage}>
-      href={editUrl}
-      target="_blank"
-      rel="noreferrer noopener"
-      className={ThemeClassNames.common.editThisPage}>
       <IconEdit />
       <Translate
         id="theme.common.editThisPage"
         description="The link label to edit the current page">
         Edit this page
       </Translate>
-    </a>
+    </Link>
   );
 }

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

@@ -9,6 +9,7 @@ import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
 import type {Props} from '@theme/Heading';
 
 import styles from './styles.module.css';
@@ -34,16 +35,16 @@ export default function Heading({as: As, id, ...props}: Props): JSX.Element {
       )}
       id={id}>
       {props.children}
-      <a
+      <Link
         className="hash-link"
-        href={`#${id}`}
+        to={`#${id}`}
         title={translate({
           id: 'theme.common.headingLinkTitle',
           message: 'Direct link to heading',
           description: 'Title for link to heading',
         })}>
         &#8203;
-      </a>
+      </Link>
     </As>
   );
 }

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

@@ -7,7 +7,6 @@
 
 import React from 'react';
 import {SkipToContentLink} from '@docusaurus/theme-common';
-
 import styles from './styles.module.css';
 
 export default function SkipToContent(): JSX.Element {

packages/docusaurus-theme-classic/src/theme/TOCItems/Tree.tsx

@@ -6,6 +6,7 @@
  */
 
 import React from 'react';
+import Link from '@docusaurus/Link';
 import type {Props} from '@theme/TOCItems/Tree';
 
 // Recursive component rendering the toc tree
@@ -22,12 +23,10 @@ function TOCItemTree({
     <ul className={isChild ? undefined : className}>
       {toc.map((heading) => (
         <li key={heading.id}>
-          {/* eslint-disable-next-line jsx-a11y/control-has-associated-label */}
+          <Link
-          <a
+            to={`#${heading.id}`}
-            href={`#${heading.id}`}
             className={linkClassName ?? undefined}
             // Developer provided the HTML, so assume it's safe.
-            // eslint-disable-next-line react/no-danger
             dangerouslySetInnerHTML={{__html: heading.value}}
           />
           <TOCItemTree

packages/docusaurus-theme-common/src/utils/skipToContentUtils.tsx

@@ -90,6 +90,7 @@ export function SkipToContentLink(props: SkipToContentLinkProps): JSX.Element {
       ref={containerRef}
       role="region"
       aria-label={DefaultSkipToContentLabel}>
+      {/* eslint-disable-next-line @docusaurus/no-html-links */}
       <a
         {...props}
         // Note this is a fallback href in case JS is disabled

packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx

@@ -426,10 +426,8 @@ function SearchPageContent(): JSX.Element {
               'text--right',
               styles.searchLogoColumn,
             )}>
-            <a
+            <Link
-              target="_blank"
+              to="https://www.algolia.com/"
-              rel="noopener noreferrer"
-              href="https://www.algolia.com/"
               aria-label={translate({
                 id: 'theme.SearchPage.algoliaLabel',
                 message: 'Search by Algolia',
@@ -451,7 +449,7 @@ function SearchPageContent(): JSX.Element {
                   />
                 </g>
               </svg>
-            </a>
+            </Link>
           </div>
         </div>
 

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

@@ -148,7 +148,7 @@ function Link(
   }
 
   return isRegularHtmlLink ? (
-    // eslint-disable-next-line jsx-a11y/anchor-has-content
+    // eslint-disable-next-line jsx-a11y/anchor-has-content, @docusaurus/no-html-links
     <a
       ref={innerRef}
       href={targetLink}

packages/eslint-plugin/src/index.ts

@@ -14,6 +14,7 @@ export = {
       plugins: ['@docusaurus'],
       rules: {
         '@docusaurus/string-literal-i18n-messages': 'error',
+        '@docusaurus/no-html-links': 'warn',
       },
     },
     all: {
@@ -21,6 +22,7 @@ export = {
       rules: {
         '@docusaurus/string-literal-i18n-messages': 'error',
         '@docusaurus/no-untranslated-text': 'warn',
+        '@docusaurus/no-html-links': 'warn',
       },
     },
   },

packages/eslint-plugin/src/rules/__tests__/no-html-links.test.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 rule from '../no-html-links';
+import {RuleTester} from './testUtils';
+
+const errorsJSX = [{messageId: 'link'}] as const;
+
+const ruleTester = new RuleTester({
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+});
+
+ruleTester.run('prefer-docusaurus-link', rule, {
+  valid: [
+    {
+      code: '<Link to="/test">test</Link>',
+    },
+    {
+      code: '<Link to="https://twitter.com/docusaurus">Twitter</Link>',
+    },
+    {
+      code: '<a href="https://twitter.com/docusaurus">Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+    },
+    {
+      code: '<a href={`https://twitter.com/docusaurus`}>Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+    },
+    {
+      code: '<a href="mailto:viktor@malmedal.dev">Contact</a>  ',
+      options: [{ignoreFullyResolved: true}],
+    },
+    {
+      code: '<a href="tel:123456789">Call</a>',
+      options: [{ignoreFullyResolved: true}],
+    },
+  ],
+  invalid: [
+    {
+      code: '<a href="/test">test</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="https://twitter.com/docusaurus" target="_blank">test</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="https://twitter.com/docusaurus" target="_blank" rel="noopener noreferrer">test</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="mailto:viktor@malmedal.dev">Contact</a>  ',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="tel:123456789">Call</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href={``}>Twitter</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href={`https://www.twitter.com/docusaurus`}>Twitter</a>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<a href="www.twitter.com/docusaurus">Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+      errors: errorsJSX,
+    },
+    {
+      // TODO we might want to make this test pass
+      // Can template literals be statically pre-evaluated? (Babel can do it)
+      // eslint-disable-next-line no-template-curly-in-string
+      code: '<a href={`https://twitter.com/${"docu" + "saurus"} ${"rex"}`}>Twitter</a>',
+      options: [{ignoreFullyResolved: true}],
+      errors: errorsJSX,
+    },
+  ],
+});

packages/eslint-plugin/src/rules/index.ts

@@ -5,10 +5,12 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import noHtmlLinks from './no-html-links';
 import noUntranslatedText from './no-untranslated-text';
 import stringLiteralI18nMessages from './string-literal-i18n-messages';
 
 export default {
   'no-untranslated-text': noUntranslatedText,
   'string-literal-i18n-messages': stringLiteralI18nMessages,
+  'no-html-links': noHtmlLinks,
 };

packages/eslint-plugin/src/rules/no-html-links.ts

@@ -0,0 +1,103 @@
+/**
+ * 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 {createRule} from '../util';
+import type {TSESTree} from '@typescript-eslint/types/dist/ts-estree';
+
+const docsUrl = 'https://docusaurus.io/docs/docusaurus-core#link';
+
+type Options = [
+  {
+    ignoreFullyResolved: boolean;
+  },
+];
+
+type MessageIds = 'link';
+
+function isFullyResolvedUrl(urlString: string): boolean {
+  try {
+    // href gets coerced to a string when it gets rendered anyway
+    const url = new URL(String(urlString));
+    if (url.protocol) {
+      return true;
+    }
+  } catch (e) {}
+  return false;
+}
+
+export default createRule<Options, MessageIds>({
+  name: 'no-html-links',
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'enforce using Docusaurus Link component instead of <a> tag',
+      recommended: false,
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          ignoreFullyResolved: {
+            type: 'boolean',
+          },
+        },
+        additionalProperties: false,
+      },
+    ],
+    messages: {
+      link: `Do not use an \`<a>\` element to navigate. Use the \`<Link />\` component from \`@docusaurus/Link\` instead. See: ${docsUrl}`,
+    },
+  },
+  defaultOptions: [
+    {
+      ignoreFullyResolved: false,
+    },
+  ],
+
+  create(context, [options]) {
+    const {ignoreFullyResolved} = options;
+
+    return {
+      JSXOpeningElement(node) {
+        if ((node.name as TSESTree.JSXIdentifier).name !== 'a') {
+          return;
+        }
+
+        if (ignoreFullyResolved) {
+          const hrefAttr = node.attributes.find(
+            (attr): attr is TSESTree.JSXAttribute =>
+              attr.type === 'JSXAttribute' && attr.name.name === 'href',
+          );
+
+          if (hrefAttr?.value?.type === 'Literal') {
+            if (isFullyResolvedUrl(String(hrefAttr.value.value))) {
+              return;
+            }
+          }
+          if (hrefAttr?.value?.type === 'JSXExpressionContainer') {
+            const container: TSESTree.JSXExpressionContainer = hrefAttr.value;
+            const {expression} = container;
+            if (expression.type === 'TemplateLiteral') {
+              // Simple static string template literals
+              if (
+                expression.expressions.length === 0 &&
+                expression.quasis.length === 1 &&
+                expression.quasis[0]?.type === 'TemplateElement' &&
+                isFullyResolvedUrl(String(expression.quasis[0].value.raw))
+              ) {
+                return;
+              }
+              // TODO add more complex TemplateLiteral cases here
+            }
+          }
+        }
+
+        context.report({node, messageId: 'link'});
+      },
+    };
+  },
+});

website/_dogfooding/_pages tests/hydration-tests.tsx

@@ -6,28 +6,17 @@
  */
 
 import React from 'react';
+import Link from '@docusaurus/Link';
 import Layout from '@theme/Layout';
 
 // Repro for hydration issue https://github.com/facebook/docusaurus/issues/5617
 function BuggyText() {
   return (
     <span>
-      Built using the{' '}
+      Built using the <Link to="https://www.electronjs.org/">Electron</Link> ,
-      <a href="https://www.electronjs.org/" target="_blank" rel="noreferrer">
+      based on <Link to="https://www.chromium.org/">Chromium</Link>, and written
-        Electron
+      using <Link to="https://www.typescriptlang.org/">TypeScript</Link> ,
-      </a>{' '}
+      Xplorer promises you an unprecedented experience.
-      , based on{' '}
-      <a href="https://www.chromium.org/" target="_blank" rel="noreferrer">
-        Chromium
-      </a>
-      , and written using{' '}
-      <a
-        href="https://www.typescriptlang.org/"
-        target="_blank"
-        rel="noreferrer">
-        TypeScript
-      </a>{' '}
-      , Xplorer promises you an unprecedented experience.
     </span>
   );
 }

website/docs/api/misc/eslint-plugin/README.md

@@ -52,6 +52,7 @@ For more fine-grained control, you can also enable the plugin manually and confi
 | --- | --- | --- |
 | [`@docusaurus/no-untranslated-text`](./no-untranslated-text.md) | Enforce text labels in JSX to be wrapped by translate calls |  |
 | [`@docusaurus/string-literal-i18n-messages`](./string-literal-i18n-messages.md) | Enforce translate APIs to be called on plain text labels | ✅ |
+| [`@docusaurus/no-html-links`](./no-html-links.md) | Ensures @docusaurus/Link is used instead of `<a>` tags | ✅ |
 
 ✅ = recommended
 

website/docs/api/misc/eslint-plugin/no-html-links.md

@@ -0,0 +1,45 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/no-html-links
+---
+
+# no-html-links
+
+Ensure that the Docusaurus [`<Link>`](../../../docusaurus-core.md#link) component is used instead of `<a>` tags.
+
+The `<Link>` component has prefetching and preloading built-in. It also does build-time broken link detection, and helps Docusaurus understand your site's structure better.
+
+## Rule Details {#details}
+
+Examples of **incorrect** code for this rule:
+
+```html
+<a href="/page">go to page!</a>
+
+<a href="https://twitter.com/docusaurus" target="_blank">Twitter</a>
+```
+
+Examples of **correct** code for this rule:
+
+```js
+import Link from '@docusaurus/Link'
+
+<Link to="/page">go to page!</Link>
+
+<Link to="https://twitter.com/docusaurus">Twitter</Link>
+```
+
+## Rule Configuration {#configuration}
+
+Accepted fields:
+
+```mdx-code-block
+<APITable>
+```
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ignoreFullyResolved` | `boolean` | `false` | Set to true will not report any `<a>` tags with absolute URLs including a protocol. |
+
+```mdx-code-block
+</APITable>
+```

website/src/components/HackerNewsIcon.tsx

@@ -6,6 +6,7 @@
  */
 
 import React from 'react';
+import Link from '@docusaurus/Link';
 
 export default function HackerNewsIcon({
   size = 54,
@@ -13,10 +14,8 @@ export default function HackerNewsIcon({
   size?: number;
 }): JSX.Element {
   return (
-    <a
+    <Link
-      href="https://news.ycombinator.com/item?id=32303052"
+      to="https://news.ycombinator.com/item?id=32303052"
-      target="_blank"
-      rel="noreferrer"
       style={{display: 'block', width: size, height: size}}>
       <svg
         xmlns="http://www.w3.org/2000/svg"
@@ -30,6 +29,6 @@ export default function HackerNewsIcon({
           d="M23 32h2v-6l5.5-10h-2.1L24 24.1 19.6 16h-2.1L23 26z"
         />
       </svg>
-    </a>
+    </Link>
   );
 }

website/src/components/ProductHuntCard.tsx

@@ -7,6 +7,7 @@
 
 import type {ComponentProps} from 'react';
 import React from 'react';
+import Link from '@docusaurus/Link';
 
 export default function ProductHuntCard({
   className,
@@ -16,10 +17,8 @@ export default function ProductHuntCard({
   style?: ComponentProps<'a'>['style'];
 }): JSX.Element {
   return (
-    <a
+    <Link
-      href="https://www.producthunt.com/posts/docusaurus-2-0?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-docusaurus-2-0"
+      to="https://www.producthunt.com/posts/docusaurus-2-0?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-docusaurus-2-0"
-      target="_blank"
-      rel="noreferrer"
       className={className}
       style={{display: 'block', width: 250, height: 54, ...style}}>
       <img
@@ -29,6 +28,6 @@ export default function ProductHuntCard({
         width={250}
         height={54}
       />
-    </a>
+    </Link>
   );
 }

website/src/components/TeamProfileCards/index.tsx

@@ -53,14 +53,14 @@ function TeamProfileCard({
         <div className="card__footer">
           <div className="button-group button-group--block">
             {githubUrl && (
-              <a className="button button--secondary" href={githubUrl}>
+              <Link className="button button--secondary" href={githubUrl}>
                 GitHub
-              </a>
+              </Link>
             )}
             {twitterUrl && (
-              <a className="button button--secondary" href={twitterUrl}>
+              <Link className="button button--secondary" href={twitterUrl}>
                 Twitter
-              </a>
+              </Link>
             )}
           </div>
         </div>

website/src/components/Tweet/index.tsx

@@ -9,6 +9,7 @@ import React, {type ReactNode} from 'react';
 
 import clsx from 'clsx';
 
+import Link from '@docusaurus/Link';
 import styles from './styles.module.css';
 
 export interface Props {
@@ -50,9 +51,9 @@ export default function Tweet({
       <div className={clsx('card__body', styles.tweet)}>{content}</div>
 
       <div className="card__footer">
-        <a className={clsx(styles.tweetMeta, styles.tweetDate)} href={url}>
+        <Link className={clsx(styles.tweetMeta, styles.tweetDate)} to={url}>
           {date}
-        </a>
+        </Link>
       </div>
     </div>
   );

website/src/components/TweetQuote/index.tsx

@@ -9,6 +9,7 @@ import React, {type ReactNode} from 'react';
 
 import clsx from 'clsx';
 
+import Link from '@docusaurus/Link';
 import styles from './styles.module.css';
 
 export interface Props {
@@ -31,12 +32,10 @@ export default function TweetQuote({
   return (
     <figure className={styles.tweetQuote}>
       <blockquote>
-        <a href={url} target="_blank" rel="noreferrer nofollow">
+        <Link to={url}>{children}</Link>
-          {children}
-        </a>
       </blockquote>
       <figcaption>
-        <a href={profileUrl} target="_blank" rel="noreferrer nofollow">
+        <Link to={profileUrl} rel="nofollow">
           <div className="avatar">
             <img
               alt={name}
@@ -53,7 +52,7 @@ export default function TweetQuote({
               </small>
             </div>
           </div>
-        </a>
+        </Link>
       </figcaption>
     </figure>
   );

website/src/components/Versions.tsx

@@ -15,6 +15,7 @@ import React, {
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 import {useVersions} from '@docusaurus/plugin-content-docs/client';
 import Translate from '@docusaurus/Translate';
+import Link from '@docusaurus/Link';
 import CodeBlock from '@theme/CodeBlock';
 
 type ContextValue = {
@@ -113,9 +114,9 @@ export function StableMajorVersion(): JSX.Element {
 
 function GitBranchLink({branch}: {branch: string}): JSX.Element {
   return (
-    <a href={`https://github.com/facebook/docusaurus/tree/${branch}`}>
+    <Link to={`https://github.com/facebook/docusaurus/tree/${branch}`}>
       <code>{branch}</code>
-    </a>
+    </Link>
   );
 }
 

website/src/pages/showcase/index.tsx

@@ -12,6 +12,7 @@ import Translate, {translate} from '@docusaurus/Translate';
 import {useHistory, useLocation} from '@docusaurus/router';
 import {usePluralForm} from '@docusaurus/theme-common';
 
+import Link from '@docusaurus/Link';
 import Layout from '@theme/Layout';
 import FavoriteIcon from '@site/src/components/svgIcons/FavoriteIcon';
 import {
@@ -123,15 +124,11 @@ function ShowcaseHeader() {
     <section className="margin-top--lg margin-bottom--lg text--center">
       <h1>{TITLE}</h1>
       <p>{DESCRIPTION}</p>
-      <a
+      <Link className="button button--primary" to={SUBMIT_URL}>
-        className="button button--primary"
-        href={SUBMIT_URL}
-        target="_blank"
-        rel="noreferrer">
         <Translate id="showcase.header.button">
           🙏 Please add your site
         </Translate>
-      </a>
+      </Link>
     </section>
   );
 }

website/src/pages/versions.tsx

@@ -81,9 +81,9 @@ export default function Version(): JSX.Element {
                   </Link>
                 </td>
                 <td>
-                  <a href={`${repoUrl}/releases/tag/v${latestVersion.name}`}>
+                  <Link to={`${repoUrl}/releases/tag/v${latestVersion.name}`}>
                     <ReleaseNotesLabel />
-                  </a>
+                  </Link>
                 </td>
               </tr>
             </tbody>