Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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

Merged
merged 17 commits into from
Apr 15, 2021
Merged

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

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
9ba149d
Merge pull request #113 from facebook/master
lisa761 Feb 15, 2021
b9b6700
Merge pull request #115 from facebook/master
javidrashid Feb 23, 2021
2e9033f
Merge pull request #116 from facebook/master
javidrashid Feb 25, 2021
80714d5
Merge pull request #117 from facebook/master
lisa761 Mar 2, 2021
8e087f7
chore: add theme classnames for blog pages
Mar 24, 2021
137bc84
Merge branch 'master' into ShinteiMai/global-css-blogs
Mar 26, 2021
0998a58
fix: component syntax error in blog pages
Mar 26, 2021
9879cda
style: fix camelcase issue with theme class names
Mar 31, 2021
33eb927
chore: add theme classnames for doc page and mdx page
Mar 31, 2021
f3c72dc
chore: make wrapper classnames in blog and doc page into constants
Mar 31, 2021
0171ae2
chore: add main wrapper theme class name for layout component
Apr 5, 2021
aedab82
fix: change wrong theme classnames and improve naming
Apr 5, 2021
8eb8962
chore: add wrapper theme class name for mdx page
Apr 5, 2021
6260100
docs: add docs for theme class names
Apr 5, 2021
d75143f
docs: use raw-loader to import documentation and add some comments
Apr 15, 2021
1ffc4cf
docs: provide more detail to comment
Apr 15, 2021
0c92a20
chore: rename ThemeClassname.ts to ThemeClassName.ts
Apr 15, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion packages/docusaurus-theme-classic/src/theme/BlogListPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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',
Expand Down
4 changes: 3 additions & 1 deletion packages/docusaurus-theme-classic/src/theme/BlogPostPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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">
Expand Down
4 changes: 3 additions & 1 deletion packages/docusaurus-theme-classic/src/theme/BlogTagsListPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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',
Expand Down
5 changes: 3 additions & 2 deletions packages/docusaurus-theme-classic/src/theme/BlogTagsPostsPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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() {
Expand Down Expand Up @@ -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',
Expand Down
5 changes: 3 additions & 2 deletions packages/docusaurus-theme-classic/src/theme/DocPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -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),
Expand Down
12 changes: 10 additions & 2 deletions packages/docusaurus-theme-classic/src/theme/Layout/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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();

Expand All @@ -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>
Expand Down
4 changes: 3 additions & 1 deletion packages/docusaurus-theme-classic/src/theme/MDXPage/index.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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">
Expand Down
1 change: 1 addition & 0 deletions packages/docusaurus-theme-classic/src/types.d.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,7 @@ declare module '@theme/Layout' {
keywords?: string | string[];
permalink?: string;
wrapperClassName?: string;
pageClassName?: string;
searchMetadatas?: {
version?: string;
tag?: string;
Expand Down
2 changes: 2 additions & 0 deletions packages/docusaurus-theme-common/src/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,3 +34,5 @@ export {
} from './utils/docsPreferredVersion/useDocsPreferredVersion';

export {DocsPreferredVersionContextProvider} from './utils/docsPreferredVersion/DocsPreferredVersionProvider';

export {ThemeClassNames} from './utils/ThemeClassnames';
23 changes: 23 additions & 0 deletions packages/docusaurus-theme-common/src/utils/ThemeClassnames.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
/**
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved
* 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.
*/

export const ThemeClassNames = {
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I mean add a little // comment here so that someone reading the code understands why we created this file in the first place. Nothing too complicated, just 1 line

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',
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's remove the redundant prefix here for more consistency.

Suggested change
docPages: 'main-docs-wrapper',
docPages: 'docs-wrapper',

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lex111 we already have main-docs-wrapper and it is used in a css selector by ourselves + other sites already, so this would be a breaking change.

I'd be happy to normalize those wrapper names, but maybe we can handle the breaking changes in an upcoming PR that focus only on the breaking changes?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah yes, agree with you, I don't think that such BC will affect many people, especially since this is a relatively new addition, so now is good time to normalize it.

mdxPages: 'mdx-wrapper',
},
};
23 changes: 23 additions & 0 deletions website/docs/styling-layout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -101,6 +101,29 @@ function MyComponent() {
}
```

#### Theme Class Names

`@docusarus/theme-common` provides 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.
stevenhansel marked this conversation as resolved.
Show resolved Hide resolved

```ts
export const ThemeClassNames = {
Copy link
Collaborator

@slorber slorber Apr 6, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we refactor ThemeClassNames isn't there a risk to forget to update this code snippet, and we end up with a code snippet and actual classnames not in sync over time?

That's why I suggested using something similar to the Crowdin config here, to ensure we display in the code block the real code, so that it stays in sync automatically.

### Example configuration {#example-configuration}

The **Docusaurus v2 configuration file** is a good example of using versioning and multi-instance:

import CrowdinConfigV2 from '!!raw-loader!@site/../crowdin-v2.yaml';
import CodeBlock from '@theme/CodeBlock';

<CodeBlock className="language-yaml" title="test">
  {CrowdinConfigV2.split('\n')
    // remove comments
    .map((line) => !line.startsWith('#') && line)
    .filter(Boolean)
    .join('\n')}
</CodeBlock>

https://docusaurus.io/docs/i18n/crowdin#example-configuration

You can probably use something like this to import the file content as a string, and display it in a code block:

import ThemeClassNamesCode from '!!raw-loader!@theme-common/src/utils/ThemeClassNames.ts';

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, I see. I didn't get what you meant before, going to import it from that file now.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have updated the documentation and imported the code by using raw-loader but right now I imported it like this:
import ThemeClassNamesCode from '!!raw-loader!@site/../packages/docusaurus-theme-common/src/utils/ThemeClassNames.ts'; import CodeBlock from '@theme/CodeBlock';

Is there a way to import it from @theme-common? because I tried before and it couldn't find the file.

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

### 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).
Expand Down