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

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

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>

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

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

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

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.

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"

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