@docusaurus/theme-classic 2.0.0-beta.1ab8aa0af → 2.0.0-beta.2

package/src/theme/BlogPostItem/index.tsx

@@ -10,14 +10,14 @@ import clsx from 'clsx';
 import {MDXProvider} from '@mdx-js/react';
 import Translate, {translate} from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
+import {usePluralForm} from '@docusaurus/theme-common';
 import MDXComponents from '@theme/MDXComponents';
 import Seo from '@theme/Seo';
+import EditThisPage from '@theme/EditThisPage';
 import type {Props} from '@theme/BlogPostItem';
 
 import styles from './styles.module.css';
 
-import {usePluralForm} from '@docusaurus/theme-common';
-
 // Very simple pluralization: probably good enough for now
 function useReadingTimePlural() {
   const {selectMessage} = usePluralForm();
@@ -47,8 +47,16 @@ function BlogPostItem(props: Props): JSX.Element {
     truncated,
     isBlogPostPage = false,
   } = props;
-  const {date, formattedDate, permalink, tags, readingTime} = metadata;
-  const {author, title, image, keywords} = frontMatter;
+  const {
+    date,
+    formattedDate,
+    permalink,
+    tags,
+    readingTime,
+    title,
+    editUrl,
+  } = metadata;
+  const {author, image, keywords} = frontMatter;
 
   const authorURL = frontMatter.author_url || frontMatter.authorURL;
   const authorTitle = frontMatter.author_title || frontMatter.authorTitle;
@@ -60,20 +68,18 @@ function BlogPostItem(props: Props): JSX.Element {
 
     return (
       <header>
-        <TitleHeading
-          className={clsx('margin-bottom--sm', styles.blogPostTitle)}>
+        <TitleHeading className={styles.blogPostTitle}>
           {isBlogPostPage ? title : <Link to={permalink}>{title}</Link>}
         </TitleHeading>
-        <div className="margin-vert--md">
-          <time dateTime={date} className={styles.blogPostDate}>
-            {formattedDate}
-            {readingTime && (
-              <>
-                {' · '}
-                {readingTimePlural(readingTime)}
-              </>
-            )}
-          </time>
+        <div className={clsx(styles.blogPostData, 'margin-vert--md')}>
+          <time dateTime={date}>{formattedDate}</time>
+
+          {readingTime && (
+            <>
+              {' · '}
+              {readingTimePlural(readingTime)}
+            </>
+          )}
         </div>
         <div className="avatar margin-vert--md">
           {authorImageURL && (
@@ -84,9 +90,9 @@ function BlogPostItem(props: Props): JSX.Element {
           <div className="avatar__intro">
             {author && (
               <>
-                <h4 className="avatar__name">
+                <div className="avatar__name">
                   <Link href={authorURL}>{author}</Link>
-                </h4>
+                </div>
                 <small className="avatar__subtitle">{authorTitle}</small>
               </>
             )}
@@ -106,16 +112,19 @@ function BlogPostItem(props: Props): JSX.Element {
           <MDXProvider components={MDXComponents}>{children}</MDXProvider>
         </div>
         {(tags.length > 0 || truncated) && (
-          <footer className="row margin-vert--lg">
+          <footer
+            className={clsx('row docusaurus-mt-lg', {
+              [styles.blogPostDetailsFull]: isBlogPostPage,
+            })}>
             {tags.length > 0 && (
               <div className="col">
-                <strong>
+                <b>
                   <Translate
                     id="theme.tags.tagsListLabel"
                     description="The label alongside a tag list">
                     Tags:
                   </Translate>
-                </strong>
+                </b>
                 {tags.map(({label, permalink: tagPermalink}) => (
                   <Link
                     key={tagPermalink}
@@ -126,18 +135,25 @@ function BlogPostItem(props: Props): JSX.Element {
                 ))}
               </div>
             )}
-            {truncated && (
+
+            {isBlogPostPage && editUrl && (
+              <div className="col margin-top--sm">
+                <EditThisPage editUrl={editUrl} />
+              </div>
+            )}
+
+            {!isBlogPostPage && truncated && (
               <div className="col text--right">
                 <Link
                   to={metadata.permalink}
                   aria-label={`Read more about ${title}`}>
-                  <strong>
+                  <b>
                     <Translate
                       id="theme.blog.post.readMore"
                       description="The label used in blog post item excerpts to link to full blog posts">
                       Read More
                     </Translate>
-                  </strong>
+                  </b>
                 </Link>
               </div>
             )}

package/src/theme/BlogPostItem/styles.module.css

@@ -9,6 +9,10 @@
   font-size: 3rem;
 }
 
-.blogPostDate {
+.blogPostData {
   font-size: 0.9rem;
 }
+
+.blogPostDetailsFull {
+  flex-direction: column;
+}

package/src/theme/BlogPostPage/index.tsx

@@ -12,13 +12,12 @@ import BlogPostPaginator from '@theme/BlogPostPaginator';
 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;
   const {frontMatter, metadata} = BlogPostContents;
-  const {title, description, nextItem, prevItem, editUrl} = metadata;
+  const {title, description, nextItem, prevItem} = metadata;
   const {hide_table_of_contents: hideTableOfContents} = frontMatter;
 
   return (
@@ -30,9 +29,9 @@ function BlogPostPage(props: Props): JSX.Element {
       {BlogPostContents && (
         <div className="container margin-vert--lg">
           <div className="row">
-            <div className="col col--3">
+            <aside className="col col--3">
               <BlogSidebar sidebar={sidebar} />
-            </div>
+            </aside>
             <main className="col col--7">
               <BlogPostItem
                 frontMatter={frontMatter}
@@ -40,11 +39,8 @@ function BlogPostPage(props: Props): JSX.Element {
                 isBlogPostPage>
                 <BlogPostContents />
               </BlogPostItem>
-              <div>{editUrl && <EditThisPage editUrl={editUrl} />}</div>
               {(nextItem || prevItem) && (
-                <div className="margin-vert--xl">
-                  <BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />
-                </div>
+                <BlogPostPaginator nextItem={nextItem} prevItem={prevItem} />
               )}
             </main>
             {!hideTableOfContents && BlogPostContents.toc && (

package/src/theme/BlogPostPaginator/index.tsx

@@ -15,7 +15,7 @@ function BlogPostPaginator(props: Props): JSX.Element {
 
   return (
     <nav
-      className="pagination-nav"
+      className="pagination-nav docusaurus-mt-lg"
       aria-label={translate({
         id: 'theme.blog.post.paginator.navAriaLabel',
         message: 'Blog post page navigation',

package/src/theme/BlogSidebar/index.tsx

@@ -10,14 +10,23 @@ import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import type {Props} from '@theme/BlogSidebar';
 import styles from './styles.module.css';
+import {translate} from '@docusaurus/Translate';
 
 export default function BlogSidebar({sidebar}: Props): JSX.Element | null {
   if (sidebar.items.length === 0) {
     return null;
   }
   return (
-    <div className={clsx(styles.sidebar, 'thin-scrollbar')}>
-      <h3 className={styles.sidebarItemTitle}>{sidebar.title}</h3>
+    <nav
+      className={clsx(styles.sidebar, 'thin-scrollbar')}
+      aria-label={translate({
+        id: 'theme.blog.sidebar.navAriaLabel',
+        message: 'Blog recent posts navigation',
+        description: 'The ARIA label for recent posts in the blog sidebar',
+      })}>
+      <div className={clsx(styles.sidebarItemTitle, 'margin-bottom--md')}>
+        {sidebar.title}
+      </div>
       <ul className={styles.sidebarItemList}>
         {sidebar.items.map((item) => {
           return (
@@ -33,6 +42,6 @@ export default function BlogSidebar({sidebar}: Props): JSX.Element | null {
           );
         })}
       </ul>
-    </div>
+    </nav>
   );
 }

package/src/theme/BlogSidebar/styles.module.css

@@ -6,7 +6,6 @@
  */
 
 .sidebar {
-  display: inherit;
   max-height: calc(100vh - (var(--ifm-navbar-height) + 2rem));
   overflow-y: auto;
   position: sticky;
@@ -14,25 +13,24 @@
 }
 
 .sidebarItemTitle {
-  margin-bottom: 0.5rem;
+  font-size: var(--ifm-h3-font-size);
+  font-weight: var(--ifm-font-weight-bold);
 }
 
 .sidebarItemList {
-  overflow-y: auto;
+  list-style: none;
   font-size: 0.9rem;
   padding-left: 0;
 }
 
 .sidebarItem {
-  list-style-type: none;
-  margin: 0.8rem 0;
+  margin-top: 0.7rem;
 }
 
 .sidebarItemLink {
   color: var(--ifm-font-color-base);
 }
 .sidebarItemLink:hover {
-  color: var(--ifm-color-primary);
   text-decoration: none;
 }
 .sidebarItemLinkActive {

package/src/theme/BlogTagsListPage/index.tsx

@@ -11,7 +11,7 @@ import Layout from '@theme/Layout';
 import Link from '@docusaurus/Link';
 import type {Props} from '@theme/BlogTagsListPage';
 import BlogSidebar from '@theme/BlogSidebar';
-import Translate from '@docusaurus/Translate';
+import {translate} from '@docusaurus/Translate';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function getCategoryOfTag(tag: string) {
@@ -21,6 +21,11 @@ function getCategoryOfTag(tag: string) {
 
 function BlogTagsListPage(props: Props): JSX.Element {
   const {tags, sidebar} = props;
+  const title = translate({
+    id: 'theme.tags.tagsPageTitle',
+    message: 'Tags',
+    description: 'The title of the tag list page',
+  });
 
   const tagCategories: {[category: string]: string[]} = {};
   Object.keys(tags).forEach((tag) => {
@@ -28,16 +33,13 @@ function BlogTagsListPage(props: Props): JSX.Element {
     tagCategories[category] = tagCategories[category] || [];
     tagCategories[category].push(tag);
   });
-  const tagsList = Object.entries(tagCategories).sort(([a], [b]) => {
-    if (a === b) {
-      return 0;
-    }
-    return a > b ? 1 : -1;
-  });
+  const tagsList = Object.entries(tagCategories).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
   const tagsSection = tagsList
     .map(([category, tagsForCategory]) => (
-      <div key={category}>
-        <h3>{category}</h3>
+      <article key={category}>
+        <h2>{category}</h2>
         {tagsForCategory.map((tag) => (
           <Link
             className="padding-right--md"
@@ -47,14 +49,13 @@ function BlogTagsListPage(props: Props): JSX.Element {
           </Link>
         ))}
         <hr />
-      </div>
+      </article>
     ))
     .filter((item) => item != null);
 
   return (
     <Layout
-      title="Tags"
-      description="Blog Tags"
+      title={title}
       wrapperClassName={ThemeClassNames.wrapper.blogPages}
       pageClassName={ThemeClassNames.page.blogTagsListPage}
       searchMetadatas={{
@@ -63,18 +64,12 @@ function BlogTagsListPage(props: Props): JSX.Element {
       }}>
       <div className="container margin-vert--lg">
         <div className="row">
-          <div className="col col--3">
+          <aside className="col col--3">
             <BlogSidebar sidebar={sidebar} />
-          </div>
+          </aside>
           <main className="col col--7">
-            <h1>
-              <Translate
-                id="theme.tags.tagsPageTitle"
-                description="The title of the tag list page">
-                Tags
-              </Translate>
-            </h1>
-            <div className="margin-vert--lg">{tagsSection}</div>
+            <h1>{title}</h1>
+            <section className="margin-vert--lg">{tagsSection}</section>
           </main>
         </div>
       </div>

package/src/theme/BlogTagsPostsPage/index.tsx

@@ -33,32 +33,22 @@ function useBlogPostsPlural() {
     );
 }
 
-function BlogTagsPostPageTitle({
-  tagName,
-  count,
-}: {
-  tagName: string;
-  count: number;
-}) {
-  const blogPostsPlural = useBlogPostsPlural();
-  return (
-    <Translate
-      id="theme.blog.tagTitle"
-      description="The title of the page for a blog tag"
-      values={{nPosts: blogPostsPlural(count), tagName}}>
-      {'{nPosts} tagged with "{tagName}"'}
-    </Translate>
-  );
-}
-
 function BlogTagsPostPage(props: Props): JSX.Element {
   const {metadata, items, sidebar} = props;
   const {allTagsPath, name: tagName, count} = metadata;
+  const blogPostsPlural = useBlogPostsPlural();
+  const title = translate(
+    {
+      id: 'theme.blog.tagTitle',
+      description: 'The title of the page for a blog tag',
+      message: '{nPosts} tagged with "{tagName}"',
+    },
+    {nPosts: blogPostsPlural(count), tagName},
+  );
 
   return (
     <Layout
-      title={`Posts tagged "${tagName}"`}
-      description={`Blog | Tagged "${tagName}"`}
+      title={title}
       wrapperClassName={ThemeClassNames.wrapper.blogPages}
       pageClassName={ThemeClassNames.page.blogTagsPostPage}
       searchMetadatas={{
@@ -67,31 +57,31 @@ function BlogTagsPostPage(props: Props): JSX.Element {
       }}>
       <div className="container margin-vert--lg">
         <div className="row">
-          <div className="col col--3">
+          <aside className="col col--3">
             <BlogSidebar sidebar={sidebar} />
-          </div>
+          </aside>
           <main className="col col--7">
-            <h1>
-              <BlogTagsPostPageTitle count={count} tagName={tagName} />
-            </h1>
-            <Link href={allTagsPath}>
-              <Translate
-                id="theme.tags.tagsPageLink"
-                description="The label of the link targeting the tag list page">
-                View All Tags
-              </Translate>
-            </Link>
-            <div className="margin-vert--xl">
-              {items.map(({content: BlogPostContent}) => (
-                <BlogPostItem
-                  key={BlogPostContent.metadata.permalink}
-                  frontMatter={BlogPostContent.frontMatter}
-                  metadata={BlogPostContent.metadata}
-                  truncated>
-                  <BlogPostContent />
-                </BlogPostItem>
-              ))}
-            </div>
+            <header className="margin-bottom--xl">
+              <h1>{title}</h1>
+
+              <Link href={allTagsPath}>
+                <Translate
+                  id="theme.tags.tagsPageLink"
+                  description="The label of the link targeting the tag list page">
+                  View All Tags
+                </Translate>
+              </Link>
+            </header>
+
+            {items.map(({content: BlogPostContent}) => (
+              <BlogPostItem
+                key={BlogPostContent.metadata.permalink}
+                frontMatter={BlogPostContent.frontMatter}
+                metadata={BlogPostContent.metadata}
+                truncated>
+                <BlogPostContent />
+              </BlogPostItem>
+            ))}
           </main>
         </div>
       </div>

package/src/theme/CodeBlock/index.tsx

@@ -207,13 +207,14 @@ export default function CodeBlock({
             </div>
           )}
           <div className={clsx(styles.codeBlockContent, language)}>
-            <div
+            <pre
               /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
               tabIndex={0}
               className={clsx(className, styles.codeBlock, 'thin-scrollbar', {
                 [styles.codeBlockWithTitle]: codeBlockTitle,
-              })}>
-              <div className={styles.codeBlockLines} style={style}>
+              })}
+              style={style}>
+              <code className={styles.codeBlockLines}>
                 {tokens.map((line, i) => {
                   if (line.length === 1 && line[0].content === '') {
                     line[0].content = '\n'; // eslint-disable-line no-param-reassign
@@ -222,19 +223,19 @@ export default function CodeBlock({
                   const lineProps = getLineProps({line, key: i});
 
                   if (highlightLines.includes(i + 1)) {
-                    lineProps.className = `${lineProps.className} docusaurus-highlight-code-line`;
+                    lineProps.className += ' docusaurus-highlight-code-line';
                   }
 
                   return (
-                    <div key={i} {...lineProps}>
+                    <span key={i} {...lineProps}>
                       {line.map((token, key) => (
                         <span key={key} {...getTokenProps({token, key})} />
                       ))}
-                    </div>
+                    </span>
                   );
                 })}
-              </div>
-            </div>
+              </code>
+            </pre>
 
             <button
               ref={button}
@@ -244,7 +245,7 @@ export default function CodeBlock({
                 message: 'Copy code to clipboard',
                 description: 'The ARIA label for copy code blocks button',
               })}
-              className={clsx(styles.copyButton)}
+              className={clsx(styles.copyButton, 'clean-btn')}
               onClick={handleCopyCode}>
               {showCopied ? (
                 <Translate

package/src/theme/CodeBlock/styles.module.css

@@ -25,8 +25,7 @@
 }
 
 .codeBlock {
-  overflow: auto;
-  border-radius: var(--ifm-global-radius);
+  padding: 0;
 }
 
 .codeBlockWithTitle {
@@ -36,10 +35,8 @@
 
 .copyButton {
   background: rgba(0, 0, 0, 0.3);
-  border: none;
   border-radius: var(--ifm-global-radius);
   color: var(--ifm-color-white);
-  cursor: pointer;
   opacity: 0;
   user-select: none;
   padding: 0.4rem 0.5rem;
@@ -56,12 +53,12 @@
 }
 
 .codeBlockLines {
-  font: var(--ifm-code-font-size) / var(--ifm-pre-line-height)
-    var(--ifm-font-family-monospace);
-  white-space: pre;
+  font: inherit;
   float: left;
   min-width: 100%;
   padding: var(--ifm-pre-padding);
+  display: flex;
+  flex-direction: column;
 }
 
 @media print {

package/src/theme/DocItem/index.tsx

@@ -7,23 +7,20 @@
 
 import React from 'react';
 import DocPaginator from '@theme/DocPaginator';
-import DocVersionSuggestions from '@theme/DocVersionSuggestions';
+import DocVersionBanner from '@theme/DocVersionBanner';
 import Seo from '@theme/Seo';
 import LastUpdated from '@theme/LastUpdated';
 import type {Props} from '@theme/DocItem';
 import TOC from '@theme/TOC';
 import EditThisPage from '@theme/EditThisPage';
+import {MainHeading} from '@theme/Heading';
 
 import clsx from 'clsx';
 import styles from './styles.module.css';
-import {
-  useActivePlugin,
-  useVersions,
-  useActiveVersion,
-} from '@theme/hooks/useDocs';
+import {useActivePlugin, useVersions} from '@theme/hooks/useDocs';
 
 function DocItem(props: Props): JSX.Element {
-  const {content: DocContent} = props;
+  const {content: DocContent, versionMetadata} = props;
   const {metadata, frontMatter} = DocContent;
   const {
     image,
@@ -42,64 +39,67 @@ function DocItem(props: Props): JSX.Element {
 
   const {pluginId} = useActivePlugin({failfast: true});
   const versions = useVersions(pluginId);
-  const version = useActiveVersion(pluginId);
 
   // If site is not versioned or only one version is included
   // we don't show the version badge
   // See https://github.com/facebook/docusaurus/issues/3362
   const showVersionBadge = versions.length > 1;
 
-  // For meta title, using frontMatter.title in priority over a potential # title found in markdown
-  // See https://github.com/facebook/docusaurus/issues/4665#issuecomment-825831367
-  const metaTitle = frontMatter.title || title;
+  // We only add a title if:
+  // - user asks to hide it with frontmatter
+  // - the markdown content does not already contain a top-level h1 heading
+  const shouldAddTitle =
+    !hideTitle && typeof DocContent.contentTitle === 'undefined';
 
   return (
     <>
-      <Seo {...{title: metaTitle, description, keywords, image}} />
+      <Seo {...{title, description, keywords, image}} />
 
       <div className="row">
         <div
           className={clsx('col', {
             [styles.docItemCol]: !hideTableOfContents,
           })}>
-          <DocVersionSuggestions />
+          <DocVersionBanner versionMetadata={versionMetadata} />
           <div className={styles.docItemContainer}>
             <article>
               {showVersionBadge && (
-                <div>
-                  <span className="badge badge--secondary">
-                    Version: {version.label}
-                  </span>
-                </div>
-              )}
-              {!hideTitle && (
-                <header>
-                  <h1 className={styles.docTitle}>{title}</h1>
-                </header>
+                <span className="badge badge--secondary">
+                  Version: {versionMetadata.label}
+                </span>
               )}
+
               <div className="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
+                See https://github.com/facebook/docusaurus/pull/4882#issuecomment-853021120
+                */}
+                {shouldAddTitle && <MainHeading>{title}</MainHeading>}
+
                 <DocContent />
               </div>
-            </article>
-            {(editUrl || lastUpdatedAt || lastUpdatedBy) && (
-              <div className="margin-vert--xl">
-                <div className="row">
+
+              {(editUrl || lastUpdatedAt || lastUpdatedBy) && (
+                <footer className="row docusaurus-mt-lg">
                   <div className="col">
                     {editUrl && <EditThisPage editUrl={editUrl} />}
                   </div>
-                  {(lastUpdatedAt || lastUpdatedBy) && (
-                    <LastUpdated
-                      lastUpdatedAt={lastUpdatedAt}
-                      formattedLastUpdatedAt={formattedLastUpdatedAt}
-                      lastUpdatedBy={lastUpdatedBy}
-                    />
-                  )}
-                </div>
-              </div>
-            )}
-            <div className="margin-vert--lg">
-              <DocPaginator metadata={metadata} />
-            </div>
+
+                  <div className={clsx('col', styles.lastUpdated)}>
+                    {(lastUpdatedAt || lastUpdatedBy) && (
+                      <LastUpdated
+                        lastUpdatedAt={lastUpdatedAt}
+                        formattedLastUpdatedAt={formattedLastUpdatedAt}
+                        lastUpdatedBy={lastUpdatedBy}
+                      />
+                    )}
+                  </div>
+                </footer>
+              )}
+            </article>
+
+            <DocPaginator metadata={metadata} />
           </div>
         </div>
         {!hideTableOfContents && DocContent.toc && (