From cd47d8a81534c70aa1bcc08bab66220ec92f30f9 Mon Sep 17 00:00:00 2001
From: Steven Hansel <stevenhanselgo@gmail.com>
Date: Thu, 15 Apr 2021 23:36:40 +0700
Subject: [PATCH] feat(v2): add unique page/wrapper className to each theme
 pages (#4511)

* chore: add theme classnames for blog pages

* fix: component syntax error in blog pages

* style: fix camelcase issue with theme class names

* chore: add theme classnames for doc page and mdx page

* chore: make wrapper classnames in blog and doc page into constants

* chore: add main wrapper theme class name for layout component

* fix: change wrong theme classnames and improve naming

* chore: add wrapper theme class name for mdx page

* docs: add docs for theme class names

* docs: use raw-loader to import documentation and add some comments

* docs: provide more detail to comment

* chore: rename ThemeClassname.ts to ThemeClassName.ts

Co-authored-by: Lisa Chandra <52909743+lisa761@users.noreply.github.com>
Co-authored-by: Javid <singularity.javid@gmail.com>
---
 .../src/theme/BlogListPage/index.tsx          |  4 +++-
 .../src/theme/BlogPostPage/index.tsx          |  4 +++-
 .../src/theme/BlogTagsListPage/index.tsx      |  4 +++-
 .../src/theme/BlogTagsPostsPage/index.tsx     |  5 ++--
 .../src/theme/DocPage/index.tsx               |  5 ++--
 .../src/theme/Layout/index.tsx                | 12 ++++++++--
 .../src/theme/MDXPage/index.tsx               |  4 +++-
 .../docusaurus-theme-classic/src/types.d.ts   |  1 +
 packages/docusaurus-theme-common/src/index.ts |  2 ++
 .../src/utils/ThemeClassNames.ts              | 24 +++++++++++++++++++
 website/docs/styling-layout.md                | 12 ++++++++++
 11 files changed, 67 insertions(+), 10 deletions(-)
 create mode 100644 packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts

diff --git a/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx
index 76bcedd218..393602c90b 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx
+++ b/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',
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogPostPage/index.tsx
index f8e0e51933..bb911ebdb4 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogPostPage/index.tsx
+++ b/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">
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
index 8ce584d975..2bdb11905b 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
+++ b/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',
diff --git a/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
index 2832432a11..0d9f0d48c6 100644
--- a/packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
+++ b/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',
diff --git a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
index 242cacfd6a..43df6ea6cc 100644
--- a/packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
+++ b/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),
diff --git a/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx b/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx
index 58ae9e349c..64a8bd79b7 100644
--- a/packages/docusaurus-theme-classic/src/theme/Layout/index.tsx
+++ b/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>
diff --git a/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx b/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx
index c0c9d4b94e..1b523d9658 100644
--- a/packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx
+++ b/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">
diff --git a/packages/docusaurus-theme-classic/src/types.d.ts b/packages/docusaurus-theme-classic/src/types.d.ts
index a22bfcd7f1..114e977f77 100644
--- a/packages/docusaurus-theme-classic/src/types.d.ts
+++ b/packages/docusaurus-theme-classic/src/types.d.ts
@@ -249,6 +249,7 @@ declare module '@theme/Layout' {
     keywords?: string | string[];
     permalink?: string;
     wrapperClassName?: string;
+    pageClassName?: string;
     searchMetadatas?: {
       version?: string;
       tag?: string;
diff --git a/packages/docusaurus-theme-common/src/index.ts b/packages/docusaurus-theme-common/src/index.ts
index 5792d43862..6d5243f3ef 100644
--- a/packages/docusaurus-theme-common/src/index.ts
+++ b/packages/docusaurus-theme-common/src/index.ts
@@ -38,3 +38,5 @@ export {
 } from './utils/docsPreferredVersion/useDocsPreferredVersion';
 
 export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';
+
+export {ThemeClassNames} from './utils/ThemeClassNames';
diff --git a/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts b/packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts
new file mode 100644
index 0000000000..8f545f7380
--- /dev/null
+++ b/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',
+  },
+};
diff --git a/website/docs/styling-layout.md b/website/docs/styling-layout.md
index b83b09e39d..aadc18c3c9 100644
--- a/website/docs/styling-layout.md
+++ b/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).