From 90e7e321d1c1e3d39583f73b8ac3ca319f029c05 Mon Sep 17 00:00:00 2001
From: Devansu Yadav <devansuyadav@gmail.com>
Date: Thu, 19 Jan 2023 21:38:24 +0530
Subject: [PATCH] feat(eslint-plugin): new prefer-docusaurus-heading rule
 (#8384)

---
 .eslintrc.js                                  | 10 +++
 .../src/components/HomepageFeatures/index.tsx |  3 +-
 .../classic-typescript/src/pages/index.tsx    |  5 +-
 .../src/components/HomepageFeatures/index.js  |  3 +-
 .../templates/classic/src/pages/index.js      |  5 +-
 .../src/theme/BlogArchivePage/index.tsx       |  9 ++-
 .../src/theme/BlogTagsListPage/index.tsx      |  3 +-
 .../src/theme/BlogTagsPostsPage/index.tsx     |  3 +-
 .../src/theme/DocCard/index.tsx               |  8 ++-
 .../src/theme/DocTagDocListPage/index.tsx     |  5 +-
 .../src/theme/DocTagsListPage/index.tsx       |  3 +-
 .../src/theme/ErrorPageContent.tsx            |  5 +-
 .../src/theme/NotFound/Content/index.tsx      |  5 +-
 .../src/theme/TagsListByLetter/index.tsx      |  6 +-
 .../src/theme/SearchPage/index.tsx            |  8 +--
 packages/eslint-plugin/src/index.ts           |  2 +
 .../prefer-docusaurus-heading.test.ts         | 69 +++++++++++++++++++
 packages/eslint-plugin/src/rules/index.ts     |  2 +
 .../src/rules/prefer-docusaurus-heading.ts    | 46 +++++++++++++
 .../_dogfooding/_pages tests/analytics.tsx    |  3 +-
 .../_pages tests/error-boundary-tests.tsx     |  4 +-
 .../docs/api/misc/eslint-plugin/README.mdx    |  1 +
 .../prefer-docusaurus-heading.mdx             | 31 +++++++++
 website/src/components/Playground/index.tsx   |  3 +-
 .../src/components/TeamProfileCards/index.tsx |  5 +-
 website/src/pages/index.tsx                   | 21 +++---
 .../_components/ShowcaseCard/index.tsx        |  5 +-
 website/src/pages/showcase/index.tsx          | 19 ++---
 website/src/pages/versions.tsx                |  4 +-
 .../theme/ChangelogList/Header/index.tsx      |  5 +-
 website/src/theme/Admonition/Types.tsx        |  5 +-
 31 files changed, 254 insertions(+), 52 deletions(-)
 create mode 100644 packages/eslint-plugin/src/rules/__tests__/prefer-docusaurus-heading.test.ts
 create mode 100644 packages/eslint-plugin/src/rules/prefer-docusaurus-heading.ts
 create mode 100644 website/docs/api/misc/eslint-plugin/prefer-docusaurus-heading.mdx

diff --git a/.eslintrc.js b/.eslintrc.js
index 56851d0247c3..1acb68f82e64 100644
--- a/.eslintrc.js
+++ b/.eslintrc.js
@@ -375,6 +375,7 @@ module.exports = {
     '@typescript-eslint/no-unused-vars': [ERROR, {ignoreRestSiblings: true}],
     '@typescript-eslint/prefer-optional-chain': ERROR,
     '@docusaurus/no-html-links': ERROR,
+    '@docusaurus/prefer-docusaurus-heading': ERROR,
     '@docusaurus/no-untranslated-text': [
       WARNING,
       {
@@ -495,5 +496,14 @@ module.exports = {
       files: ['packages/eslint-plugin/**/*.{js,ts}'],
       extends: ['plugin:eslint-plugin/recommended'],
     },
+    {
+      files: [
+        'packages/docusaurus-plugin-debug/**',
+        'packages/docusaurus/src/**',
+      ],
+      rules: {
+        '@docusaurus/prefer-docusaurus-heading': OFF,
+      },
+    },
   ],
 };
diff --git a/packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx b/packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx
index 91ef4601d2fc..75cd587bb065 100644
--- a/packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx
+++ b/packages/create-docusaurus/templates/classic-typescript/src/components/HomepageFeatures/index.tsx
@@ -1,5 +1,6 @@
 import React from 'react';
 import clsx from 'clsx';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
 type FeatureItem = {
@@ -48,7 +49,7 @@ function Feature({title, Svg, description}: FeatureItem) {
         <Svg className={styles.featureSvg} role="img" />
       </div>
       <div className="text--center padding-horiz--md">
-        <h3>{title}</h3>
+        <Heading as="h3">{title}</Heading>
         <p>{description}</p>
       </div>
     </div>
diff --git a/packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx b/packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx
index 305139fba009..056c3d953b76 100644
--- a/packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx
+++ b/packages/create-docusaurus/templates/classic-typescript/src/pages/index.tsx
@@ -4,6 +4,7 @@ import Link from '@docusaurus/Link';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
 import HomepageFeatures from '@site/src/components/HomepageFeatures';
+import Heading from '@theme/Heading';
 
 import styles from './index.module.css';
 
@@ -12,7 +13,9 @@ function HomepageHeader() {
   return (
     <header className={clsx('hero hero--primary', styles.heroBanner)}>
       <div className="container">
-        <h1 className="hero__title">{siteConfig.title}</h1>
+        <Heading as="h1" className="hero__title">
+          {siteConfig.title}
+        </Heading>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
         <div className={styles.buttons}>
           <Link
diff --git a/packages/create-docusaurus/templates/classic/src/components/HomepageFeatures/index.js b/packages/create-docusaurus/templates/classic/src/components/HomepageFeatures/index.js
index 78f410ba6888..606782543581 100644
--- a/packages/create-docusaurus/templates/classic/src/components/HomepageFeatures/index.js
+++ b/packages/create-docusaurus/templates/classic/src/components/HomepageFeatures/index.js
@@ -1,5 +1,6 @@
 import React from 'react';
 import clsx from 'clsx';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
 const FeatureList = [
@@ -42,7 +43,7 @@ function Feature({Svg, title, description}) {
         <Svg className={styles.featureSvg} role="img" />
       </div>
       <div className="text--center padding-horiz--md">
-        <h3>{title}</h3>
+        <Heading as="h3">{title}</Heading>
         <p>{description}</p>
       </div>
     </div>
diff --git a/packages/create-docusaurus/templates/classic/src/pages/index.js b/packages/create-docusaurus/templates/classic/src/pages/index.js
index affcd9099c28..282c3fad6020 100644
--- a/packages/create-docusaurus/templates/classic/src/pages/index.js
+++ b/packages/create-docusaurus/templates/classic/src/pages/index.js
@@ -5,6 +5,7 @@ import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Layout from '@theme/Layout';
 import HomepageFeatures from '@site/src/components/HomepageFeatures';
 
+import Heading from '@theme/Heading';
 import styles from './index.module.css';
 
 function HomepageHeader() {
@@ -12,7 +13,9 @@ function HomepageHeader() {
   return (
     <header className={clsx('hero hero--primary', styles.heroBanner)}>
       <div className="container">
-        <h1 className="hero__title">{siteConfig.title}</h1>
+        <Heading as="h1" className="hero__title">
+          {siteConfig.title}
+        </Heading>
         <p className="hero__subtitle">{siteConfig.tagline}</p>
         <div className={styles.buttons}>
           <Link
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogArchivePage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogArchivePage/index.tsx
index 763d0661e25f..82150becd3ee 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogArchivePage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogArchivePage/index.tsx
@@ -11,6 +11,7 @@ import {translate} from '@docusaurus/Translate';
 import {PageMetadata} from '@docusaurus/theme-common';
 import Layout from '@theme/Layout';
 import type {ArchiveBlogPost, Props} from '@theme/BlogArchivePage';
+import Heading from '@theme/Heading';
 
 type YearProp = {
   year: string;
@@ -20,7 +21,9 @@ type YearProp = {
 function Year({year, posts}: YearProp) {
   return (
     <>
-      <h3>{year}</h3>
+      <Heading as="h3" id={year}>
+        {year}
+      </Heading>
       <ul>
         {posts.map((post) => (
           <li key={post.metadata.date}>
@@ -81,7 +84,9 @@ export default function BlogArchive({archive}: Props): JSX.Element {
       <Layout>
         <header className="hero hero--primary">
           <div className="container">
-            <h1 className="hero__title">{title}</h1>
+            <Heading as="h1" className="hero__title">
+              {title}
+            </Heading>
             <p className="hero__subtitle">{description}</p>
           </div>
         </header>
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
index 46af5b4ef61d..f16e6401472b 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
@@ -17,6 +17,7 @@ import BlogLayout from '@theme/BlogLayout';
 import TagsListByLetter from '@theme/TagsListByLetter';
 import type {Props} from '@theme/BlogTagsListPage';
 import SearchMetadata from '@theme/SearchMetadata';
+import Heading from '@theme/Heading';
 
 export default function BlogTagsListPage({tags, sidebar}: Props): JSX.Element {
   const title = translateTagsPageTitle();
@@ -29,7 +30,7 @@ export default function BlogTagsListPage({tags, sidebar}: Props): JSX.Element {
       <PageMetadata title={title} />
       <SearchMetadata tag="blog_tags_list" />
       <BlogLayout sidebar={sidebar}>
-        <h1>{title}</h1>
+        <Heading as="h1">{title}</Heading>
         <TagsListByLetter tags={tags} />
       </BlogLayout>
     </HtmlClassNameProvider>
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
index 27b1c658f685..c93074a3a300 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
@@ -21,6 +21,7 @@ import SearchMetadata from '@theme/SearchMetadata';
 import type {Props} from '@theme/BlogTagsPostsPage';
 import BlogPostItems from '@theme/BlogPostItems';
 import Unlisted from '@theme/Unlisted';
+import Heading from '@theme/Heading';
 
 // Very simple pluralization: probably good enough for now
 function useBlogPostsPlural() {
@@ -73,7 +74,7 @@ function BlogTagsPostsPageContent({
     <BlogLayout sidebar={sidebar}>
       {tag.unlisted && <Unlisted />}
       <header className="margin-bottom--xl">
-        <h1>{title}</h1>
+        <Heading as="h1">{title}</Heading>
         <Link href={tag.allTagsPath}>
           <Translate
             id="theme.tags.tagsPageLink"
diff --git a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx
index 90a5a3121da0..c486df8de2a3 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocCard/index.tsx
@@ -16,6 +16,7 @@ import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';
 
 import type {Props} from '@theme/DocCard';
+import Heading from '@theme/Heading';
 import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
@@ -52,9 +53,12 @@ function CardLayout({
 }): JSX.Element {
   return (
     <CardContainer href={href}>
-      <h2 className={clsx('text--truncate', styles.cardTitle)} title={title}>
+      <Heading
+        as="h2"
+        className={clsx('text--truncate', styles.cardTitle)}
+        title={title}>
         {icon} {title}
-      </h2>
+      </Heading>
       {description && (
         <p
           className={clsx('text--truncate', styles.cardDescription)}
diff --git a/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
index b341b55c7263..aa90c75abfe0 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocTagDocListPage/index.tsx
@@ -18,6 +18,7 @@ import Translate, {translate} from '@docusaurus/Translate';
 import SearchMetadata from '@theme/SearchMetadata';
 import type {Props} from '@theme/DocTagDocListPage';
 import Unlisted from '@theme/Unlisted';
+import Heading from '@theme/Heading';
 
 // Very simple pluralization: probably good enough for now
 function useNDocsTaggedPlural() {
@@ -53,7 +54,7 @@ function DocItem({doc}: {doc: Props['tag']['items'][number]}): JSX.Element {
   return (
     <article className="margin-vert--lg">
       <Link to={doc.permalink}>
-        <h2>{doc.title}</h2>
+        <Heading as="h2">{doc.title}</Heading>
       </Link>
       {doc.description && <p>{doc.description}</p>}
     </article>
@@ -83,7 +84,7 @@ function DocTagDocListPageContent({
           <main className="col col--8 col--offset-2">
             {tag.unlisted && <Unlisted />}
             <header className="margin-bottom--xl">
-              <h1>{title}</h1>
+              <Heading as="h1">{title}</Heading>
               <Link href={tag.allTagsPath}>
                 <Translate
                   id="theme.tags.tagsPageLink"
diff --git a/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
index 5603797ab6bf..4a5af782c6df 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/DocTagsListPage/index.tsx
@@ -16,6 +16,7 @@ import {
 import TagsListByLetter from '@theme/TagsListByLetter';
 import SearchMetadata from '@theme/SearchMetadata';
 import type {Props} from '@theme/DocTagsListPage';
+import Heading from '@theme/Heading';
 
 function DocTagsListPageMetadata({
   title,
@@ -38,7 +39,7 @@ function DocTagsListPageContent({
       <div className="container margin-vert--lg">
         <div className="row">
           <main className="col col--8 col--offset-2">
-            <h1>{title}</h1>
+            <Heading as="h1">{title}</Heading>
             <TagsListByLetter tags={tags} />
           </main>
         </div>
diff --git a/packages/docusaurus-theme-classic/src/theme/ErrorPageContent.tsx b/packages/docusaurus-theme-classic/src/theme/ErrorPageContent.tsx
index a2664859ed20..6ee3b9f8b301 100644
--- a/packages/docusaurus-theme-classic/src/theme/ErrorPageContent.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/ErrorPageContent.tsx
@@ -9,6 +9,7 @@ import React from 'react';
 import Translate from '@docusaurus/Translate';
 import {ErrorBoundaryTryAgainButton} from '@docusaurus/theme-common';
 import type {Props} from '@theme/Error';
+import Heading from '@theme/Heading';
 
 export default function ErrorPageContent({
   error,
@@ -18,13 +19,13 @@ export default function ErrorPageContent({
     <main className="container margin-vert--xl">
       <div className="row">
         <div className="col col--6 col--offset-3">
-          <h1 className="hero__title">
+          <Heading as="h1" className="hero__title">
             <Translate
               id="theme.ErrorPageContent.title"
               description="The title of the fallback page when the page crashed">
               This page crashed.
             </Translate>
-          </h1>
+          </Heading>
           <p>{error.message}</p>
           <div>
             <ErrorBoundaryTryAgainButton onClick={tryAgain} />
diff --git a/packages/docusaurus-theme-classic/src/theme/NotFound/Content/index.tsx b/packages/docusaurus-theme-classic/src/theme/NotFound/Content/index.tsx
index f5288dec00e6..17684042974a 100644
--- a/packages/docusaurus-theme-classic/src/theme/NotFound/Content/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/NotFound/Content/index.tsx
@@ -9,19 +9,20 @@ import React from 'react';
 import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
 import type {Props} from '@theme/NotFound/Content';
+import Heading from '@theme/Heading';
 
 export default function NotFoundContent({className}: Props): JSX.Element {
   return (
     <main className={clsx('container margin-vert--xl', className)}>
       <div className="row">
         <div className="col col--6 col--offset-3">
-          <h1 className="hero__title">
+          <Heading as="h1" className="hero__title">
             <Translate
               id="theme.NotFound.title"
               description="The title of the 404 page">
               Page Not Found
             </Translate>
-          </h1>
+          </Heading>
           <p>
             <Translate
               id="theme.NotFound.p1"
diff --git a/packages/docusaurus-theme-classic/src/theme/TagsListByLetter/index.tsx b/packages/docusaurus-theme-classic/src/theme/TagsListByLetter/index.tsx
index 326efa0c7767..ffd28c1585b8 100644
--- a/packages/docusaurus-theme-classic/src/theme/TagsListByLetter/index.tsx
+++ b/packages/docusaurus-theme-classic/src/theme/TagsListByLetter/index.tsx
@@ -9,13 +9,15 @@ import React from 'react';
 import {listTagsByLetters, type TagLetterEntry} from '@docusaurus/theme-common';
 import Tag from '@theme/Tag';
 import type {Props} from '@theme/TagsListByLetter';
-
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
 function TagLetterEntryItem({letterEntry}: {letterEntry: TagLetterEntry}) {
   return (
     <article>
-      <h2>{letterEntry.letter}</h2>
+      <Heading as="h2" id={letterEntry.letter}>
+        {letterEntry.letter}
+      </Heading>
       <ul className="padding--none">
         {letterEntry.tags.map((tag) => (
           <li key={tag.permalink} className={styles.tag}>
diff --git a/packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx b/packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx
index 83cbf8ec66f7..1c3db1eb0dc9 100644
--- a/packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx
+++ b/packages/docusaurus-theme-search-algolia/src/theme/SearchPage/index.tsx
@@ -33,7 +33,7 @@ import {
   useSearchResultUrlProcessor,
 } from '@docusaurus/theme-search-algolia/client';
 import Layout from '@theme/Layout';
-
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
 // Very simple pluralization: probably good enough for now
@@ -374,7 +374,7 @@ function SearchPageContent(): JSX.Element {
       </Head>
 
       <div className="container margin-vert--lg">
-        <h1>{getTitle()}</h1>
+        <Heading as="h1">{getTitle()}</Heading>
 
         <form className="row" onSubmit={(e) => e.preventDefault()}>
           <div
@@ -455,9 +455,9 @@ function SearchPageContent(): JSX.Element {
             {searchResultState.items.map(
               ({title, url, summary, breadcrumbs}, i) => (
                 <article key={i} className={styles.searchResultItem}>
-                  <h2 className={styles.searchResultItemHeading}>
+                  <Heading as="h2" className={styles.searchResultItemHeading}>
                     <Link to={url} dangerouslySetInnerHTML={{__html: title}} />
-                  </h2>
+                  </Heading>
 
                   {breadcrumbs.length > 0 && (
                     <nav aria-label="breadcrumbs">
diff --git a/packages/eslint-plugin/src/index.ts b/packages/eslint-plugin/src/index.ts
index 9d652293b44b..65c0b0ee3d2c 100644
--- a/packages/eslint-plugin/src/index.ts
+++ b/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',
       },
     },
   },
diff --git a/packages/eslint-plugin/src/rules/__tests__/prefer-docusaurus-heading.test.ts b/packages/eslint-plugin/src/rules/__tests__/prefer-docusaurus-heading.test.ts
new file mode 100644
index 000000000000..7a9cd815cc49
--- /dev/null
+++ b/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,
+    },
+  ],
+});
diff --git a/packages/eslint-plugin/src/rules/index.ts b/packages/eslint-plugin/src/rules/index.ts
index 85409ddfb473..caa726907faa 100644
--- a/packages/eslint-plugin/src/rules/index.ts
+++ b/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,
 };
diff --git a/packages/eslint-plugin/src/rules/prefer-docusaurus-heading.ts b/packages/eslint-plugin/src/rules/prefer-docusaurus-heading.ts
new file mode 100644
index 000000000000..4a3853d9f379
--- /dev/null
+++ b/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'});
+      },
+    };
+  },
+});
diff --git a/website/_dogfooding/_pages tests/analytics.tsx b/website/_dogfooding/_pages tests/analytics.tsx
index c3c52ce8212e..c03b83bdfe02 100644
--- a/website/_dogfooding/_pages tests/analytics.tsx	
+++ b/website/_dogfooding/_pages tests/analytics.tsx	
@@ -7,12 +7,13 @@
 
 import React from 'react';
 import Layout from '@theme/Layout';
+import Heading from '@theme/Heading';
 
 // See https://github.com/facebook/docusaurus/issues/6337#issuecomment-1012913647
 export default function Analytics(): JSX.Element {
   return (
     <Layout>
-      <h1>Test Analytics</h1>
+      <Heading as="h1">Test Analytics</Heading>
       <div>
         <button
           type="button"
diff --git a/website/_dogfooding/_pages tests/error-boundary-tests.tsx b/website/_dogfooding/_pages tests/error-boundary-tests.tsx
index 100c7e6c0d2f..c724b152c142 100644
--- a/website/_dogfooding/_pages tests/error-boundary-tests.tsx	
+++ b/website/_dogfooding/_pages tests/error-boundary-tests.tsx	
@@ -8,7 +8,7 @@
 import React from 'react';
 import Interpolate from '@docusaurus/Interpolate';
 import Layout from '@theme/Layout';
-
+import Heading from '@theme/Heading';
 import ErrorBoundaryTestButton from '@site/src/components/ErrorBoundaryTestButton';
 
 export default function ErrorBoundaryTests(): JSX.Element {
@@ -17,7 +17,7 @@ export default function ErrorBoundaryTests(): JSX.Element {
       <ErrorBoundaryTestButton>Crash outside layout</ErrorBoundaryTestButton>
       <Layout>
         <main className="container margin-vert--xl">
-          <h1>Error boundary tests</h1>
+          <Heading as="h1">Error boundary tests</Heading>
           <div>
             <ErrorBoundaryTestButton>
               Crash inside layout
diff --git a/website/docs/api/misc/eslint-plugin/README.mdx b/website/docs/api/misc/eslint-plugin/README.mdx
index 59bc8f51a2cf..a0d41ee4d458 100644
--- a/website/docs/api/misc/eslint-plugin/README.mdx
+++ b/website/docs/api/misc/eslint-plugin/README.mdx
@@ -53,6 +53,7 @@ For more fine-grained control, you can also enable the plugin manually and confi
 | [`@docusaurus/no-untranslated-text`](./no-untranslated-text.mdx) | Enforce text labels in JSX to be wrapped by translate calls |  |
 | [`@docusaurus/string-literal-i18n-messages`](./string-literal-i18n-messages.mdx) | Enforce translate APIs to be called on plain text labels | ✅ |
 | [`@docusaurus/no-html-links`](./no-html-links.mdx) | Ensures @docusaurus/Link is used instead of `<a>` tags | ✅ |
+| [`@docusaurus/prefer-docusaurus-heading`](./prefer-docusaurus-heading.mdx) | Ensures @theme/Heading is used instead of `<hn>` tags for headings | ✅ |
 
 ✅ = recommended
 
diff --git a/website/docs/api/misc/eslint-plugin/prefer-docusaurus-heading.mdx b/website/docs/api/misc/eslint-plugin/prefer-docusaurus-heading.mdx
new file mode 100644
index 000000000000..e1d758898d70
--- /dev/null
+++ b/website/docs/api/misc/eslint-plugin/prefer-docusaurus-heading.mdx
@@ -0,0 +1,31 @@
+---
+slug: /api/misc/@docusaurus/eslint-plugin/prefer-docusaurus-heading
+---
+
+# prefer-docusaurus-heading
+
+Ensures that the `@theme/Heading` theme component provided by Docusaurus [`theme-classic`](../../themes/theme-classic.mdx) is used instead of `<hn>` tags for headings.
+
+## Rule Details {#details}
+
+Examples of **incorrect** code for this rule:
+
+```html
+<h1>This is heading 1</h1>
+
+<h2>This is heading 2</h2>
+
+<h3>This is heading 3</h3>
+```
+
+Examples of **correct** code for this rule:
+
+```javascript
+import Heading from '@theme/Heading'
+
+<Heading as='h1'>This is heading 1</Heading>
+
+<Heading as='h2'>This is heading 2</Heading>
+
+<Heading as='h3'>This is heading 3</Heading>
+```
diff --git a/website/src/components/Playground/index.tsx b/website/src/components/Playground/index.tsx
index a661c965c270..7b3dddb4a664 100644
--- a/website/src/components/Playground/index.tsx
+++ b/website/src/components/Playground/index.tsx
@@ -12,6 +12,7 @@ import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
 import Image from '@theme/IdealImage';
+import Heading from '@theme/Heading';
 
 const Playgrounds = [
   {
@@ -64,7 +65,7 @@ function PlaygroundCard({name, image, url, description}: Props) {
           </Link>
         </div>
         <div className="card__body">
-          <h3>{name}</h3>
+          <Heading as="h3">{name}</Heading>
           <p>{description}</p>
         </div>
         <div className="card__footer">
diff --git a/website/src/components/TeamProfileCards/index.tsx b/website/src/components/TeamProfileCards/index.tsx
index 9738cb42ccdb..ecf959d48cf4 100644
--- a/website/src/components/TeamProfileCards/index.tsx
+++ b/website/src/components/TeamProfileCards/index.tsx
@@ -8,6 +8,7 @@
 import React, {type ReactNode} from 'react';
 import Translate from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
+import Heading from '@theme/Heading';
 
 function WebsiteLink({to, children}: {to: string; children?: ReactNode}) {
   return (
@@ -45,7 +46,9 @@ function TeamProfileCard({
               alt={`${name}'s avatar`}
             />
             <div className="avatar__intro">
-              <h3 className="avatar__name">{name}</h3>
+              <Heading as="h3" className="avatar__name">
+                {name}
+              </Heading>
             </div>
           </div>
         </div>
diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx
index ad5c477f38bb..eddc8452ec22 100644
--- a/website/src/pages/index.tsx
+++ b/website/src/pages/index.tsx
@@ -25,12 +25,13 @@ import ProductHuntCard from '@site/src/components/ProductHuntCard';
 import HackerNewsIcon from '@site/src/components/HackerNewsIcon';
 import styles from './styles.module.css';
 import 'react-lite-youtube-embed/dist/LiteYouTubeEmbed.css';
+import Heading from '@theme/Heading';
 
 function HeroBanner() {
   return (
     <div className={styles.hero} data-theme="dark">
       <div className={styles.heroInner}>
-        <h1 className={styles.heroProjectTagline}>
+        <Heading as="h1" className={styles.heroProjectTagline}>
           <img
             alt={translate({message: 'Docusaurus with Keytar'})}
             className={styles.heroLogo}
@@ -51,7 +52,7 @@ function HeroBanner() {
               }),
             }}
           />
-        </h1>
+        </Heading>
         <div className={styles.indexCtas}>
           <Link className="button button--primary" to="/docs">
             <Translate>Get Started</Translate>
@@ -109,9 +110,9 @@ function TweetsSection() {
   return (
     <div className={clsx(styles.section, styles.sectionAlt)}>
       <div className="container">
-        <h2 className={clsx('margin-bottom--lg', 'text--center')}>
+        <Heading as="h2" className={clsx('margin-bottom--lg', 'text--center')}>
           <Translate>Loved by many engineers</Translate>
-        </h2>
+        </Heading>
         <div className={clsx('row', styles.tweetsSection)}>
           {tweetColumns.map((tweetItems, i) => (
             <div className="col col--4" key={i}>
@@ -161,9 +162,9 @@ function VideoContainer() {
     <div className="container text--center margin-bottom--xl">
       <div className="row">
         <div className="col">
-          <h2>
+          <Heading as="h2">
             <Translate>Check it out in the intro video</Translate>
-          </h2>
+          </Heading>
           <div className="video-container">
             <LiteYouTubeEmbed
               id="_An9EsKPhp0"
@@ -198,7 +199,9 @@ function Feature({
         src={withBaseUrl(feature.image.src)}
         loading="lazy"
       />
-      <h3 className={clsx(styles.featureHeading)}>{feature.title}</h3>
+      <Heading as="h3" className={clsx(styles.featureHeading)}>
+        {feature.title}
+      </Heading>
       <p className="padding-horiz--md">{feature.text}</p>
     </div>
   );
@@ -210,9 +213,9 @@ function FeaturesContainer() {
 
   return (
     <div className="container text--center">
-      <h2>
+      <Heading as="h2">
         <Translate>Main features</Translate>
-      </h2>
+      </Heading>
       <div className="row margin-bottom--lg">
         {firstRow.map((feature, idx) => (
           <Feature feature={feature} key={idx} />
diff --git a/website/src/pages/showcase/_components/ShowcaseCard/index.tsx b/website/src/pages/showcase/_components/ShowcaseCard/index.tsx
index f4d1f68cb20f..5bf6935e12e7 100644
--- a/website/src/pages/showcase/_components/ShowcaseCard/index.tsx
+++ b/website/src/pages/showcase/_components/ShowcaseCard/index.tsx
@@ -19,6 +19,7 @@ import {
   type Tag,
 } from '@site/src/data/users';
 import {sortBy} from '@site/src/utils/jsUtils';
+import Heading from '@theme/Heading';
 import Tooltip from '../ShowcaseTooltip';
 import styles from './styles.module.css';
 
@@ -76,11 +77,11 @@ function ShowcaseCard({user}: {user: User}) {
       </div>
       <div className="card__body">
         <div className={clsx(styles.showcaseCardHeader)}>
-          <h4 className={styles.showcaseCardTitle}>
+          <Heading as="h4" className={styles.showcaseCardTitle}>
             <Link href={user.website} className={styles.showcaseCardLink}>
               {user.title}
             </Link>
-          </h4>
+          </Heading>
           {user.tags.includes('favorite') && (
             <FavoriteIcon svgClass={styles.svgIconFavorite} size="small" />
           )}
diff --git a/website/src/pages/showcase/index.tsx b/website/src/pages/showcase/index.tsx
index 489027fad3cd..f1411951881a 100644
--- a/website/src/pages/showcase/index.tsx
+++ b/website/src/pages/showcase/index.tsx
@@ -22,6 +22,7 @@ import {
   type User,
   type TagType,
 } from '@site/src/data/users';
+import Heading from '@theme/Heading';
 import ShowcaseTagSelect, {
   readSearchTags,
 } from './_components/ShowcaseTagSelect';
@@ -122,7 +123,7 @@ function useFilteredUsers() {
 function ShowcaseHeader() {
   return (
     <section className="margin-top--lg margin-bottom--lg text--center">
-      <h1>{TITLE}</h1>
+      <Heading as="h1">{TITLE}</Heading>
       <p>{DESCRIPTION}</p>
       <Link className="button button--primary" to={SUBMIT_URL}>
         <Translate id="showcase.header.button">
@@ -157,9 +158,9 @@ function ShowcaseFilters() {
     <section className="container margin-top--l margin-bottom--lg">
       <div className={clsx('margin-bottom--sm', styles.filterCheckbox)}>
         <div>
-          <h2>
+          <Heading as="h2">
             <Translate id="showcase.filters.title">Filters</Translate>
-          </h2>
+          </Heading>
           <span>{siteCountPlural(filteredUsers.length)}</span>
         </div>
         <ShowcaseFilterToggle />
@@ -255,9 +256,9 @@ function ShowcaseCards() {
     return (
       <section className="margin-top--lg margin-bottom--xl">
         <div className="container padding-vert--md text--center">
-          <h2>
+          <Heading as="h2">
             <Translate id="showcase.usersList.noResult">No result</Translate>
-          </h2>
+          </Heading>
           <SearchBar />
         </div>
       </section>
@@ -275,11 +276,11 @@ function ShowcaseCards() {
                   'margin-bottom--md',
                   styles.showcaseFavoriteHeader,
                 )}>
-                <h2>
+                <Heading as="h2">
                   <Translate id="showcase.favoritesList.title">
                     Our favorites
                   </Translate>
-                </h2>
+                </Heading>
                 <FavoriteIcon svgClass={styles.svgIconFavorite} />
                 <SearchBar />
               </div>
@@ -296,9 +297,9 @@ function ShowcaseCards() {
             </div>
           </div>
           <div className="container margin-top--lg">
-            <h2 className={styles.showcaseHeader}>
+            <Heading as="h2" className={styles.showcaseHeader}>
               <Translate id="showcase.usersList.allUsers">All sites</Translate>
-            </h2>
+            </Heading>
             <ul className={clsx('clean-list', styles.showcaseList)}>
               {otherUsers.map((user) => (
                 <ShowcaseCard key={user.title} user={user} />
diff --git a/website/src/pages/versions.tsx b/website/src/pages/versions.tsx
index 8b3ba21a3486..d960f7a853bc 100644
--- a/website/src/pages/versions.tsx
+++ b/website/src/pages/versions.tsx
@@ -168,11 +168,11 @@ export default function Version(): JSX.Element {
           </div>
         )}
         <div className="margin-bottom--lg">
-          <h3 id="legacy">
+          <Heading as="h3" id="legacy">
             <Translate id="versionsPage.legacy.title">
               Docusaurus v1 (Legacy)
             </Translate>
-          </h3>
+          </Heading>
           <p>
             <Translate id="versionsPage.legacy.description">
               Here you can find documentation for legacy version of Docusaurus.
diff --git a/website/src/plugins/changelog/theme/ChangelogList/Header/index.tsx b/website/src/plugins/changelog/theme/ChangelogList/Header/index.tsx
index 768c441b49c0..b3b57978dee4 100644
--- a/website/src/plugins/changelog/theme/ChangelogList/Header/index.tsx
+++ b/website/src/plugins/changelog/theme/ChangelogList/Header/index.tsx
@@ -8,6 +8,7 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
 function TwitterLink() {
@@ -63,7 +64,9 @@ export default function ChangelogListHeader({
 }): JSX.Element {
   return (
     <header className="margin-bottom--lg">
-      <h1 style={{fontSize: '3rem'}}>{blogTitle}</h1>
+      <Heading as="h1" style={{fontSize: '3rem'}}>
+        {blogTitle}
+      </Heading>
       <p>
         <Translate
           id="changelog.description"
diff --git a/website/src/theme/Admonition/Types.tsx b/website/src/theme/Admonition/Types.tsx
index 35c572360738..c7856ef20a47 100644
--- a/website/src/theme/Admonition/Types.tsx
+++ b/website/src/theme/Admonition/Types.tsx
@@ -8,11 +8,14 @@
 import React from 'react';
 import type {Props} from '@theme/Admonition';
 import DefaultAdmonitionTypes from '@theme-original/Admonition/Types';
+import Heading from '@theme/Heading';
 
 function MyCustomAdmonition(props: Props): JSX.Element {
   return (
     <div style={{border: 'solid red', padding: 10}}>
-      <h5 style={{color: 'blue', fontSize: 30}}>{props.title}</h5>
+      <Heading as="h5" style={{color: 'blue', fontSize: 30}}>
+        {props.title}
+      </Heading>
       <div>{props.children}</div>
     </div>
   );