feat: Add docs-related stable classnames (#5445)

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

@@ -20,6 +20,7 @@ import TOCCollapsible from '@theme/TOCCollapsible';
 import {MainHeading} from '@theme/Heading';
 
 import styles from './styles.module.css';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function DocItem(props: Props): JSX.Element {
   const {content: DocContent, versionMetadata} = props;
@@ -67,7 +68,11 @@ export default function DocItem(props: Props): JSX.Element {
           <div className={styles.docItemContainer}>
             <article>
               {showVersionBadge && (
-                <span className="badge badge--secondary">
+                <span
+                  className={clsx(
+                    ThemeClassNames.docs.docVersionBadge,
+                    'badge badge--secondary',
+                  )}>
                   Version: {versionMetadata.label}
                 </span>
               )}
@@ -75,11 +80,15 @@ export default function DocItem(props: Props): JSX.Element {
               {canRenderTOC && (
                 <TOCCollapsible
                   toc={DocContent.toc}
-                  className={styles.tocMobile}
+                  className={clsx(
+                    ThemeClassNames.docs.docTocMobile,
+                    styles.tocMobile,
+                  )}
                 />
               )}
 
-              <div className="markdown">
+              <div
+                className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
                 {/*
                 Title can be declared inside md content or declared through frontmatter and added manually
                 To make both cases consistent, the added title is added under the same div.markdown block
@@ -98,7 +107,10 @@ export default function DocItem(props: Props): JSX.Element {
         </div>
         {renderTocDesktop && (
           <div className="col col--3">
-            <TOC toc={DocContent.toc} />
+            <TOC
+              toc={DocContent.toc}
+              className={ThemeClassNames.docs.docTocDesktop}
+            />
           </div>
         )}
       </div>

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

@@ -16,10 +16,15 @@ import TagsListInline, {
 } from '@theme/TagsListInline';
 
 import styles from './styles.module.css';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function TagsRow(props: TagsListInlineProps) {
   return (
-    <div className="row margin-bottom--sm">
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docFooterTagsRow,
+        'row margin-bottom--sm',
+      )}>
       <div className="col">
         <TagsListInline {...props} />
       </div>
@@ -38,7 +43,7 @@ function EditMetaRow({
   formattedLastUpdatedAt,
 }: EditMetaRowProps) {
   return (
-    <div className="row">
+    <div className={clsx(ThemeClassNames.docs.docFooterEditMetaRow, 'row')}>
       <div className="col">{editUrl && <EditThisPage editUrl={editUrl} />}</div>
 
       <div className={clsx('col', styles.lastUpdated)}>
@@ -75,7 +80,8 @@ export default function DocItemFooter(props: Props): JSX.Element {
   }
 
   return (
-    <footer className="docusaurus-mt-lg">
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, 'docusaurus-mt-lg')}>
       {canDisplayTagsRow && <TagsRow tags={tags} />}
       {canDisplayEditMetaRow && (
         <EditMetaRow

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

@@ -55,7 +55,7 @@ function DocPageContent({
 
   return (
     <Layout
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsDocPage}
       searchMetadatas={{
         version,

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

@@ -12,6 +12,7 @@ import {
   useAnnouncementBar,
   MobileSecondaryMenuFiller,
   MobileSecondaryMenuComponent,
+  ThemeClassNames,
 } from '@docusaurus/theme-common';
 import useWindowSize from '@theme/hooks/useWindowSize';
 import useScrollPosition from '@theme/hooks/useScrollPosition';
@@ -78,7 +79,7 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}: Props) {
           [styles.menuWithAnnouncementBar]:
             !isAnnouncementBarClosed && showAnnouncementBar,
         })}>
-        <ul className="menu__list">
+        <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
           <DocSidebarItems items={sidebar} activePath={path} />
         </ul>
       </nav>
@@ -93,7 +94,7 @@ const DocSidebarMobileSecondaryMenu: MobileSecondaryMenuComponent<Props> = ({
   path,
 }) => {
   return (
-    <ul className="menu__list">
+    <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
       <DocSidebarItems
         items={sidebar}
         activePath={path}

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

@@ -12,6 +12,7 @@ import {
   usePrevious,
   Collapsible,
   useCollapsible,
+  ThemeClassNames,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
@@ -117,9 +118,13 @@ function DocSidebarItemCategory({
 
   return (
     <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+      )}>
       {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
       <a
         className={clsx('menu__link', {
@@ -161,7 +166,12 @@ function DocSidebarItemLink({
   const {href, label} = item;
   const isActive = isActiveSidebarItem(item, activePath);
   return (
-    <li className="menu__list-item" key={label}>
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        'menu__list-item',
+      )}
+      key={label}>
       <Link
         className={clsx('menu__link', {
           'menu__link--active': isActive,

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

@@ -63,7 +63,7 @@ export default function DocTagDocListPage({tag}: Props): JSX.Element {
   return (
     <Layout
       title={title}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsTagDocListPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!

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

@@ -20,7 +20,7 @@ function DocTagsListPage({tags}: Props): JSX.Element {
   return (
     <Layout
       title={title}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
       pageClassName={ThemeClassNames.page.docsTagsListPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!

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

@@ -14,9 +14,13 @@ import {
   useDocVersionSuggestions,
   GlobalVersion,
 } from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+} from '@docusaurus/theme-common';
 
 import type {Props} from '@theme/DocVersionBanner';
+import clsx from 'clsx';
 
 type BannerLabelComponentProps = {
   siteTitle: string;
@@ -131,7 +135,12 @@ function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
     latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
 
   return (
-    <div className="alert alert--warning margin-bottom--md" role="alert">
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docVersionBanner,
+        'alert alert--warning margin-bottom--md',
+      )}
+      role="alert">
       <div>
         <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>

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

@@ -10,10 +10,15 @@ import Translate from '@docusaurus/Translate';
 
 import type {Props} from '@theme/EditThisPage';
 import IconEdit from '@theme/IconEdit';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 export default function EditThisPage({editUrl}: Props): JSX.Element {
   return (
-    <a href={editUrl} target="_blank" rel="noreferrer noopener">
+    <a
+      href={editUrl}
+      target="_blank"
+      rel="noreferrer noopener"
+      className={ThemeClassNames.common.editThisPage}>
       <IconEdit />
       <Translate
         id="theme.common.editThisPage"

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

@@ -8,6 +8,7 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import type {Props} from '@theme/LastUpdated';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function LastUpdatedAtDate({
   lastUpdatedAt,
@@ -57,7 +58,7 @@ export default function LastUpdated({
   lastUpdatedBy,
 }: Props): JSX.Element {
   return (
-    <>
+    <span className={ThemeClassNames.common.lastUpdated}>
       <Translate
         id="theme.lastUpdated.lastUpdatedAtBy"
         description="The sentence used to display when a page has been last updated, and by who"
@@ -84,6 +85,6 @@ export default function LastUpdated({
           <small> (Simulated during dev for better perf)</small>
         </div>
       )}
-    </>
+    </span>
   );
 }

packages/docusaurus-theme-classic/src/types.d.ts

@@ -579,6 +579,7 @@ declare module '@theme/TOC' {
 
   export type TOCProps = {
     readonly toc: readonly TOCItem[];
+    readonly className?: string;
   };
 
   export type TOCHeadingsProps = {

packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts

@@ -6,6 +6,8 @@
  */
 
 // These class names are used to style page layouts in Docusaurus
+// Those are meant to be targeted by user-provided custom CSS selectors
+// /!\ Please do not modify the classnames! This is a breaking change, and annoying for users!
 export const ThemeClassNames = {
   page: {
     blogListPage: 'blog-list-page',
@@ -22,7 +24,34 @@ export const ThemeClassNames = {
   wrapper: {
     main: 'main-wrapper',
     blogPages: 'blog-wrapper',
-    docPages: 'docs-wrapper',
+    docsPages: 'docs-wrapper',
     mdxPages: 'mdx-wrapper',
   },
+
+  // /!\ Please keep the naming convention consistent!
+  // Something like: "theme-{blog,doc,version,page}?-<suffix>"
+  common: {
+    editThisPage: 'theme-edit-this-page',
+    lastUpdated: 'theme-last-updated',
+  },
+  layout: {
+    // TODO add other stable classNames here
+  },
+  docs: {
+    docVersionBanner: 'theme-doc-version-banner',
+    docVersionBadge: 'theme-doc-version-badge',
+    docMarkdown: 'theme-doc-markdown',
+    docTocMobile: 'theme-doc-toc-mobile',
+    docTocDesktop: 'theme-doc-toc-desktop',
+    docFooter: 'theme-doc-footer',
+    docFooterTagsRow: 'theme-doc-footer-tags-row',
+    docFooterEditMetaRow: 'theme-doc-footer-edit-meta-row',
+    docSidebarMenu: 'theme-doc-sidebar-menu',
+    docSidebarItemCategory: 'theme-doc-sidebar-item-category',
+    docSidebarItemLink: 'theme-doc-sidebar-item-link',
+    // TODO add other stable classNames here
+  },
+  blog: {
+    // TODO add other stable classNames here
+  },
 };