feat(eslint-plugin): new prefer-docusaurus-heading rule (#8384)

packages/eslint-plugin/src/index.ts

@@ -15,6 +15,7 @@ export = {
       rules: {
         '@docusaurus/string-literal-i18n-messages': 'error',
         '@docusaurus/no-html-links': 'warn',
+        '@docusaurus/prefer-docusaurus-heading': 'warn',
       },
     },
     all: {
@@ -23,6 +24,7 @@ export = {
         '@docusaurus/string-literal-i18n-messages': 'error',
         '@docusaurus/no-untranslated-text': 'warn',
         '@docusaurus/no-html-links': 'warn',
+        '@docusaurus/prefer-docusaurus-heading': 'warn',
       },
     },
   },

packages/eslint-plugin/src/rules/__tests__/prefer-docusaurus-heading.test.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 '../prefer-docusaurus-heading';
+import {RuleTester} from './testUtils';
+
+const errorsJSX = [{messageId: 'headings'}] as const;
+
+const ruleTester = new RuleTester({
+  parser: '@typescript-eslint/parser',
+  parserOptions: {
+    ecmaFeatures: {
+      jsx: true,
+    },
+  },
+});
+
+ruleTester.run('prefer-docusaurus-heading', rule, {
+  valid: [
+    {
+      code: "<Heading as='h1'>heading 1</Heading>",
+    },
+    {
+      code: "<Heading as='h2'>heading 2</Heading>",
+    },
+    {
+      code: "<Heading as='h3'>heading 3</Heading>",
+    },
+    {
+      code: "<Heading as='h4'>heading 4</Heading>",
+    },
+    {
+      code: "<Heading as='h5'>heading 5</Heading>",
+    },
+    {
+      code: "<Heading as='h6'>heading 6</Heading>",
+    },
+  ],
+  invalid: [
+    {
+      code: '<h1>heading 1</h1>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<h2>heading 2</h2>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<h3>heading 3</h3>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<h4>heading 4</h4>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<h5>heading 5</h5>',
+      errors: errorsJSX,
+    },
+    {
+      code: '<h6>heading 6</h6>',
+      errors: errorsJSX,
+    },
+  ],
+});

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

@@ -6,6 +6,7 @@
  */
 
 import noHtmlLinks from './no-html-links';
+import preferDocusaurusHeading from './prefer-docusaurus-heading';
 import noUntranslatedText from './no-untranslated-text';
 import stringLiteralI18nMessages from './string-literal-i18n-messages';
 
@@ -13,4 +14,5 @@ export default {
   'no-untranslated-text': noUntranslatedText,
   'string-literal-i18n-messages': stringLiteralI18nMessages,
   'no-html-links': noHtmlLinks,
+  'prefer-docusaurus-heading': preferDocusaurusHeading,
 };

packages/eslint-plugin/src/rules/prefer-docusaurus-heading.ts

@@ -0,0 +1,46 @@
+/**
+ * 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';
+
+type Options = [];
+type MessageIds = 'headings';
+
+export default createRule<Options, MessageIds>({
+  name: 'prefer-docusaurus-heading',
+  meta: {
+    type: 'problem',
+    docs: {
+      description:
+        'enforce using Docusaurus theme Heading component instead of any <hn> tag',
+      recommended: false,
+    },
+    schema: [],
+    messages: {
+      headings:
+        'Do not use any of the `<hn>` tags for headings. Use the `<Heading />` component from `@theme/Heading` instead.',
+    },
+  },
+  defaultOptions: [],
+
+  create(context) {
+    const headingTypes = ['h1', 'h2', 'h3', 'h4', 'h5', 'h6'];
+
+    return {
+      JSXOpeningElement(node) {
+        const elementName = (node.name as TSESTree.JSXIdentifier).name;
+
+        if (!headingTypes.includes(elementName)) {
+          return;
+        }
+
+        context.report({node, messageId: 'headings'});
+      },
+    };
+  },
+});