feat(v2): add unique page/wrapper className to each theme pages

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

@@ -13,6 +13,7 @@ import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';
 import type {Props} from '@theme/BlogListPage';
 import BlogSidebar from '@theme/BlogSidebar';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function BlogListPage(props: Props): JSX.Element {
   const {metadata, items, sidebar} = props;
@@ -26,7 +27,8 @@ function BlogListPage(props: Props): JSX.Element {
     <Layout
       title={title}
       description={blogDescription}
-      wrapperClassName="blog-wrapper"
+      wrapperClassName={ThemeClassNames.wrapper.blogPages}
+      pageClassName={ThemeClassNames.page.blogListPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_posts_list',

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

@@ -13,6 +13,7 @@ import type {Props} from '@theme/BlogPostPage';
 import BlogSidebar from '@theme/BlogSidebar';
 import TOC from '@theme/TOC';
 import EditThisPage from '@theme/EditThisPage';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function BlogPostPage(props: Props): JSX.Element {
   const {content: BlogPostContents, sidebar} = props;
@@ -24,7 +25,8 @@ function BlogPostPage(props: Props): JSX.Element {
     <Layout
       title={title}
       description={description}
-      wrapperClassName="blog-wrapper">
+      wrapperClassName={ThemeClassNames.wrapper.blogPages}
+      pageClassName={ThemeClassNames.page.blogPostPage}>
       {BlogPostContents && (
         <div className="container margin-vert--lg">
           <div className="row">

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

@@ -12,6 +12,7 @@ import Link from '@docusaurus/Link';
 import type {Props} from '@theme/BlogTagsListPage';
 import BlogSidebar from '@theme/BlogSidebar';
 import Translate from '@docusaurus/Translate';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function getCategoryOfTag(tag: string) {
   // tag's category should be customizable
@@ -54,7 +55,8 @@ function BlogTagsListPage(props: Props): JSX.Element {
     <Layout
       title="Tags"
       description="Blog Tags"
-      wrapperClassName="blog-wrapper"
+      wrapperClassName={ThemeClassNames.wrapper.blogPages}
+      pageClassName={ThemeClassNames.page.blogTagsListPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_tags_list',

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

@@ -13,7 +13,7 @@ import Link from '@docusaurus/Link';
 import type {Props} from '@theme/BlogTagsPostsPage';
 import BlogSidebar from '@theme/BlogSidebar';
 import Translate, {translate} from '@docusaurus/Translate';
-import {usePluralForm} from '@docusaurus/theme-common';
+import {ThemeClassNames, usePluralForm} from '@docusaurus/theme-common';
 
 // Very simple pluralization: probably good enough for now
 function useBlogPostsPlural() {
@@ -59,7 +59,8 @@ function BlogTagsPostPage(props: Props): JSX.Element {
     <Layout
       title={`Posts tagged "${tagName}"`}
       description={`Blog | Tagged "${tagName}"`}
-      wrapperClassName="blog-wrapper"
+      wrapperClassName={ThemeClassNames.wrapper.blogPages}
+      pageClassName={ThemeClassNames.page.blogTagsPostPage}
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_tags_posts',

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

@@ -23,7 +23,7 @@ import {translate} from '@docusaurus/Translate';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
-import {docVersionSearchTag} from '@docusaurus/theme-common';
+import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
 
 type DocPageContentProps = {
   readonly currentDocRoute: DocumentRoute;
@@ -54,7 +54,8 @@ function DocPageContent({
   return (
     <Layout
       key={isClient}
-      wrapperClassName="main-docs-wrapper"
+      wrapperClassName={ThemeClassNames.wrapper.docPages}
+      pageClassName={ThemeClassNames.page.docPage}
       searchMetadatas={{
         version,
         tag: docVersionSearchTag(pluginId, version),

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

@@ -15,10 +15,11 @@ import LayoutProviders from '@theme/LayoutProviders';
 import LayoutHead from '@theme/LayoutHead';
 import type {Props} from '@theme/Layout';
 import useKeyboardNavigation from '@theme/hooks/useKeyboardNavigation';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 import './styles.css';
 
 function Layout(props: Props): JSX.Element {
-  const {children, noFooter, wrapperClassName} = props;
+  const {children, noFooter, wrapperClassName, pageClassName} = props;
 
   useKeyboardNavigation();
 
@@ -32,7 +33,14 @@ function Layout(props: Props): JSX.Element {
 
       <Navbar />
 
-      <div className={clsx('main-wrapper', wrapperClassName)}>{children}</div>
+      <div
+        className={clsx(
+          ThemeClassNames.wrapper.main,
+          wrapperClassName,
+          pageClassName,
+        )}>
+        {children}
+      </div>
 
       {!noFooter && <Footer />}
     </LayoutProviders>

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

@@ -11,6 +11,7 @@ import {MDXProvider} from '@mdx-js/react';
 import MDXComponents from '@theme/MDXComponents';
 import type {Props} from '@theme/MDXPage';
 import TOC from '@theme/TOC';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function MDXPage(props: Props): JSX.Element {
   const {content: MDXPageContent} = props;
@@ -29,7 +30,8 @@ function MDXPage(props: Props): JSX.Element {
       title={title}
       description={description}
       permalink={permalink}
-      wrapperClassName={wrapperClassName}>
+      wrapperClassName={wrapperClassName ?? ThemeClassNames.wrapper.mdxPages}
+      pageClassName={ThemeClassNames.page.mdxPage}>
       <main>
         <div className="container container--fluid">
           <div className="margin-vert--lg padding-vert--lg">

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

@@ -248,6 +248,7 @@ declare module '@theme/Layout' {
     keywords?: string | string[];
     permalink?: string;
     wrapperClassName?: string;
+    pageClassName?: string;
     searchMetadatas?: {
       version?: string;
       tag?: string;

packages/docusaurus-theme-common/src/index.ts

@@ -34,3 +34,5 @@ export {
 } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 
 export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
+
+export {ThemeClassNames} from './utils/ThemeClassNames';

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

@@ -0,0 +1,24 @@
+/**
+ * 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.
+ */
+
+// These class names are used to style page layouts in Docusaurus
+export const ThemeClassNames = {
+  page: {
+    blogListPage: 'blog-list-page',
+    blogPostPage: 'blog-post-page',
+    blogTagsListPage: 'blog-tags-list-page',
+    blogTagsPostPage: 'blog-tags-post-page',
+    docPage: 'doc-page',
+    mdxPage: 'mdx-page',
+  },
+  wrapper: {
+    main: 'main-wrapper',
+    blogPages: 'blog-wrapper',
+    docPages: 'main-docs-wrapper',
+    mdxPages: 'mdx-wrapper',
+  },
+};

website/docs/styling-layout.md

@@ -101,6 +101,18 @@ function MyComponent() {
 }
 ```
 
+#### Theme Class Names
+
+We provide some predefined CSS class names to provide access for developers to style layout of a page globally in Docusaurus. The purpose is to have stable classnames shared by all themes that are meant to be targeted by custom CSS.
+
+import ThemeClassNamesCode from '!!raw-loader!@site/../packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts'; import CodeBlock from '@theme/CodeBlock';
+
+<CodeBlock className="language-ts">
+  {ThemeClassNamesCode
+    .replace(/\/\*[\s\S]*?\*\/|\/\/.*/g,'')
+    .trim()}
+</CodeBlock>
+
 ### CSS modules {#css-modules}
 
 To style your components using [CSS Modules](https://github.com/css-modules/css-modules), name your stylesheet files with the `.module.css` suffix (e.g. `welcome.module.css`). webpack will load such CSS files as CSS modules and you have to reference the class names from the imported CSS module (as opposed to using plain strings). This is similar to the convention used in [Create React App](https://facebook.github.io/create-react-app/docs/adding-a-css-modules-stylesheet).