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

.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,
+      },
+    },
   ],
 };

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>

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

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>

packages/create-docusaurus/templates/classic/src/pages/index.js

@@ -5,14 +5,17 @@ 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() {
   const {siteConfig} = useDocusaurusContext();
   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

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>

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>

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"

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)}

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"

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>

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} />

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"

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}>

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">

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',
       },
     },
   },