@docusaurus/theme-classic 2.0.0-beta.16 → 2.0.0-beta.19

package/src/nprogress.ts

@@ -0,0 +1,31 @@
+/**
+ * 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.
+ */
+
+import nprogress from 'nprogress';
+import './nprogress.css';
+import type {ClientModule} from '@docusaurus/types';
+
+nprogress.configure({showSpinner: false});
+
+const delay = 200;
+
+const clientModule: ClientModule = {
+  onRouteUpdate({location, previousLocation}) {
+    if (previousLocation && location.pathname !== previousLocation.pathname) {
+      const progressBarTimeout = window.setTimeout(() => {
+        nprogress.start();
+      }, delay);
+      return () => window.clearTimeout(progressBarTimeout);
+    }
+    return undefined;
+  },
+  onRouteDidUpdate() {
+    nprogress.done();
+  },
+};
+
+export default clientModule;

package/src/theme/BackToTopButton/index.tsx

@@ -5,122 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {useRef, useState} from 'react';
+import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
+import {ThemeClassNames, useBackToTopButton} from '@docusaurus/theme-common';
 
 import styles from './styles.module.css';
-import {
-  ThemeClassNames,
-  useScrollPosition,
-  useLocationChange,
-} from '@docusaurus/theme-common';
-
-const threshold = 300;
-
-// Not all have support for smooth scrolling (particularly Safari mobile iOS)
-// TODO proper detection is currently unreliable!
-// see https://github.com/wessberg/scroll-behavior-polyfill/issues/16
-const SupportsNativeSmoothScrolling = false;
-// const SupportsNativeSmoothScrolling =
-//   ExecutionEnvironment.canUseDOM &&
-//   'scrollBehavior' in document.documentElement.style;
-
-type CancelScrollTop = () => void;
-
-function smoothScrollTopNative(): CancelScrollTop {
-  window.scrollTo({top: 0, behavior: 'smooth'});
-  return () => {
-    // Nothing to cancel, it's natively cancelled if user tries to scroll down
-  };
-}
-
-function smoothScrollTopPolyfill(): CancelScrollTop {
-  let raf: number | null = null;
-  function rafRecursion() {
-    const currentScroll = document.documentElement.scrollTop;
-    if (currentScroll > 0) {
-      raf = requestAnimationFrame(rafRecursion);
-      window.scrollTo(0, Math.floor(currentScroll * 0.85));
-    }
-  }
-  rafRecursion();
-
-  // Break the recursion. Prevents the user from "fighting" against that
-  // recursion producing a weird UX
-  return () => raf && cancelAnimationFrame(raf);
-}
-
-type UseSmoothScrollTopReturn = {
-  // We use a cancel function because the non-native smooth scroll-top
-  // implementation must be interrupted if user scroll down
-  smoothScrollTop: () => void;
-  cancelScrollToTop: CancelScrollTop;
-};
-
-function useSmoothScrollToTop(): UseSmoothScrollTopReturn {
-  const lastCancelRef = useRef<CancelScrollTop | null>(null);
-
-  function smoothScrollTop(): void {
-    lastCancelRef.current = SupportsNativeSmoothScrolling
-      ? smoothScrollTopNative()
-      : smoothScrollTopPolyfill();
-  }
-
-  return {
-    smoothScrollTop,
-    cancelScrollToTop: () => lastCancelRef.current?.(),
-  };
-}
 
 export default function BackToTopButton(): JSX.Element {
-  const [show, setShow] = useState(false);
-  const isFocusedAnchor = useRef(false);
-  const {smoothScrollTop, cancelScrollToTop} = useSmoothScrollToTop();
-
-  useScrollPosition(({scrollY: scrollTop}, lastPosition) => {
-    const lastScrollTop = lastPosition?.scrollY;
-
-    // No lastScrollTop means component is just being mounted.
-    // Not really a scroll event from the user, so we ignore it
-    if (!lastScrollTop) {
-      return;
-    }
-
-    if (isFocusedAnchor.current) {
-      isFocusedAnchor.current = false;
-      return;
-    }
-
-    const isScrollingUp = scrollTop < lastScrollTop;
-
-    if (!isScrollingUp) {
-      cancelScrollToTop();
-    }
-
-    if (scrollTop < threshold) {
-      setShow(false);
-      return;
-    }
-
-    if (isScrollingUp) {
-      const documentHeight = document.documentElement.scrollHeight;
-      const windowHeight = window.innerHeight;
-      if (scrollTop + windowHeight < documentHeight) {
-        setShow(true);
-      }
-    } else {
-      setShow(false);
-    }
-  });
-
-  useLocationChange((locationChangeEvent) => {
-    if (locationChangeEvent.location.hash) {
-      isFocusedAnchor.current = true;
-      setShow(false);
-    }
-  });
-
+  const {shown, scrollToTop} = useBackToTopButton({threshold: 300});
   return (
     <button
       aria-label={translate({
@@ -132,12 +25,10 @@ export default function BackToTopButton(): JSX.Element {
         'clean-btn',
         ThemeClassNames.common.backToTopButton,
         styles.backToTopButton,
-        {
-          [styles.backToTopButtonShow]: show,
-        },
+        shown && styles.backToTopButtonShow,
       )}
       type="button"
-      onClick={() => smoothScrollTop()}
+      onClick={scrollToTop}
     />
   );
 }

package/src/theme/BlogArchivePage/index.tsx

@@ -10,6 +10,7 @@ import Layout from '@theme/Layout';
 import Link from '@docusaurus/Link';
 import type {ArchiveBlogPost, Props} from '@theme/BlogArchivePage';
 import {translate} from '@docusaurus/Translate';
+import {PageMetadata} from '@docusaurus/theme-common';
 
 type YearProp = {
   year: string;
@@ -50,14 +51,11 @@ function YearsSection({years}: {years: YearProp[]}) {
 }
 
 function listPostsByYears(blogPosts: readonly ArchiveBlogPost[]): YearProp[] {
-  const postsByYear: Map<string, ArchiveBlogPost[]> = blogPosts.reduceRight(
-    (posts, post) => {
-      const year = post.metadata.date.split('-')[0];
-      const yearPosts = posts.get(year) || [];
-      return posts.set(year, [post, ...yearPosts]);
-    },
-    new Map(),
-  );
+  const postsByYear = blogPosts.reduceRight((posts, post) => {
+    const year = post.metadata.date.split('-')[0]!;
+    const yearPosts = posts.get(year) ?? [];
+    return posts.set(year, [post, ...yearPosts]);
+  }, new Map<string, ArchiveBlogPost[]>());
 
   return Array.from(postsByYear, ([year, posts]) => ({
     year,
@@ -78,14 +76,17 @@ export default function BlogArchive({archive}: Props): JSX.Element {
   });
   const years = listPostsByYears(archive.blogPosts);
   return (
-    <Layout title={title} description={description}>
-      <header className="hero hero--primary">
-        <div className="container">
-          <h1 className="hero__title">{title}</h1>
-          <p className="hero__subtitle">{description}</p>
-        </div>
-      </header>
-      <main>{years.length > 0 && <YearsSection years={years} />}</main>
-    </Layout>
+    <>
+      <PageMetadata title={title} description={description} />
+      <Layout>
+        <header className="hero hero--primary">
+          <div className="container">
+            <h1 className="hero__title">{title}</h1>
+            <p className="hero__subtitle">{description}</p>
+          </div>
+        </header>
+        <main>{years.length > 0 && <YearsSection years={years} />}</main>
+      </Layout>
+    </>
   );
 }

package/src/theme/BlogLayout/index.tsx

@@ -20,11 +20,7 @@ export default function BlogLayout(props: Props): JSX.Element {
     <Layout {...layoutProps}>
       <div className="container margin-vert--lg">
         <div className="row">
-          {hasSidebar && (
-            <aside className="col col--3">
-              <BlogSidebar sidebar={sidebar!} />
-            </aside>
-          )}
+          <BlogSidebar sidebar={sidebar} />
           <main
             className={clsx('col', {
               'col--7': hasSidebar,

package/src/theme/BlogListPage/index.tsx

@@ -12,28 +12,34 @@ import BlogLayout from '@theme/BlogLayout';
 import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';
 import type {Props} from '@theme/BlogListPage';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
+import SearchMetadata from '@theme/SearchMetadata';
+import clsx from 'clsx';
 
-export default function BlogListPage(props: Props): JSX.Element {
-  const {metadata, items, sidebar} = props;
+function BlogListPageMetadata(props: Props): JSX.Element {
+  const {metadata} = props;
   const {
     siteConfig: {title: siteTitle},
   } = useDocusaurusContext();
   const {blogDescription, blogTitle, permalink} = metadata;
   const isBlogOnlyMode = permalink === '/';
   const title = isBlogOnlyMode ? siteTitle : blogTitle;
+  return (
+    <>
+      <PageMetadata title={title} description={blogDescription} />
+      <SearchMetadata tag="blog_posts_list" />
+    </>
+  );
+}
 
+function BlogListPageContent(props: Props): JSX.Element {
+  const {metadata, items, sidebar} = props;
   return (
-    <BlogLayout
-      title={title}
-      description={blogDescription}
-      wrapperClassName={ThemeClassNames.wrapper.blogPages}
-      pageClassName={ThemeClassNames.page.blogListPage}
-      searchMetadata={{
-        // assign unique search tag to exclude this page from search results!
-        tag: 'blog_posts_list',
-      }}
-      sidebar={sidebar}>
+    <BlogLayout sidebar={sidebar}>
       {items.map(({content: BlogPostContent}) => (
         <BlogPostItem
           key={BlogPostContent.metadata.permalink}
@@ -48,3 +54,16 @@ export default function BlogListPage(props: Props): JSX.Element {
     </BlogLayout>
   );
 }
+
+export default function BlogListPage(props: Props): JSX.Element {
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.blogPages,
+        ThemeClassNames.page.blogListPage,
+      )}>
+      <BlogListPageMetadata {...props} />
+      <BlogListPageContent {...props} />
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/BlogListPaginator/index.tsx

@@ -22,34 +22,31 @@ export default function BlogListPaginator(props: Props): JSX.Element {
         message: 'Blog list page navigation',
         description: 'The ARIA label for the blog pagination',
       })}>
-      <div className="pagination-nav__item">
-        {previousPage && (
-          <PaginatorNavLink
-            permalink={previousPage}
-            title={
-              <Translate
-                id="theme.blog.paginator.newerEntries"
-                description="The label used to navigate to the newer blog posts page (previous page)">
-                Newer Entries
-              </Translate>
-            }
-          />
-        )}
-      </div>
-      <div className="pagination-nav__item pagination-nav__item--next">
-        {nextPage && (
-          <PaginatorNavLink
-            permalink={nextPage}
-            title={
-              <Translate
-                id="theme.blog.paginator.olderEntries"
-                description="The label used to navigate to the older blog posts page (next page)">
-                Older Entries
-              </Translate>
-            }
-          />
-        )}
-      </div>
+      {previousPage && (
+        <PaginatorNavLink
+          permalink={previousPage}
+          title={
+            <Translate
+              id="theme.blog.paginator.newerEntries"
+              description="The label used to navigate to the newer blog posts page (previous page)">
+              Newer Entries
+            </Translate>
+          }
+        />
+      )}
+      {nextPage && (
+        <PaginatorNavLink
+          permalink={nextPage}
+          title={
+            <Translate
+              id="theme.blog.paginator.olderEntries"
+              description="The label used to navigate to the older blog posts page (next page)">
+              Older Entries
+            </Translate>
+          }
+          isNext
+        />
+      )}
     </nav>
   );
 }

package/src/theme/BlogPostAuthor/index.tsx

@@ -6,19 +6,25 @@
  */
 
 import React from 'react';
-import Link from '@docusaurus/Link';
+import Link, {type Props as LinkProps} from '@docusaurus/Link';
 import type {Props} from '@theme/BlogPostAuthor';
 
-import styles from './styles.module.css';
+function MaybeLink(props: LinkProps): JSX.Element {
+  if (props.href) {
+    return <Link {...props} />;
+  }
+  return <>{props.children}</>;
+}
 
 export default function BlogPostAuthor({author}: Props): JSX.Element {
-  const {name, title, url, imageURL} = author;
+  const {name, title, url, imageURL, email} = author;
+  const link = url || (email && `mailto:${email}`) || undefined;
   return (
     <div className="avatar margin-bottom--sm">
       {imageURL && (
-        <Link className="avatar__photo-link avatar__photo" href={url}>
-          <img className={styles.image} src={imageURL} alt={name} />
-        </Link>
+        <MaybeLink href={link} className="avatar__photo-link">
+          <img className="avatar__photo" src={imageURL} alt={name} />
+        </MaybeLink>
       )}
 
       {name && (
@@ -28,9 +34,9 @@ export default function BlogPostAuthor({author}: Props): JSX.Element {
           itemScope
           itemType="https://schema.org/Person">
           <div className="avatar__name">
-            <Link href={url} itemProp="url">
+            <MaybeLink href={link} itemProp="url">
               <span itemProp="name">{name}</span>
-            </Link>
+            </MaybeLink>
           </div>
           {title && (
             <small className="avatar__subtitle" itemProp="description">

package/src/theme/BlogPostItem/index.tsx

@@ -7,13 +7,12 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {MDXProvider} from '@mdx-js/react';
 import Translate, {translate} from '@docusaurus/Translate';
 import Link from '@docusaurus/Link';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import {usePluralForm} from '@docusaurus/theme-common';
 import {blogPostContainerID} from '@docusaurus/utils-common';
-import MDXComponents from '@theme/MDXComponents';
+import MDXContent from '@theme/MDXContent';
 import EditThisPage from '@theme/EditThisPage';
 import type {Props} from '@theme/BlogPostItem';
 
@@ -108,14 +107,15 @@ export default function BlogPostItem(props: Props): JSX.Element {
         id={isBlogPostPage ? blogPostContainerID : undefined}
         className="markdown"
         itemProp="articleBody">
-        <MDXProvider components={MDXComponents}>{children}</MDXProvider>
+        <MDXContent>{children}</MDXContent>
       </div>
 
       {(tagsExists || truncated) && (
         <footer
-          className={clsx('row docusaurus-mt-lg', {
-            [styles.blogPostDetailsFull]: isBlogPostPage,
-          })}>
+          className={clsx(
+            'row docusaurus-mt-lg',
+            isBlogPostPage && styles.blogPostDetailsFull,
+          )}>
           {tagsExists && (
             <div className={clsx('col', {'col--9': truncatedPost})}>
               <TagsListInline tags={tags} />

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

@@ -9,6 +9,15 @@
   font-size: 3rem;
 }
 
+/**
+  Blog post title should be smaller on smaller devices
+**/
+@media (max-width: 576px) {
+  .blogPostTitle {
+    font-size: 2rem;
+  }
+}
+
 .blogPostData {
   font-size: 0.9rem;
 }

package/src/theme/BlogPostPage/index.tsx

@@ -6,40 +6,63 @@
  */
 
 import React from 'react';
-import Seo from '@theme/Seo';
 import BlogLayout from '@theme/BlogLayout';
 import BlogPostItem from '@theme/BlogPostItem';
 import BlogPostPaginator from '@theme/BlogPostPaginator';
 import type {Props} from '@theme/BlogPostPage';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
 import TOC from '@theme/TOC';
+import clsx from 'clsx';
 
-export default function BlogPostPage(props: Props): JSX.Element {
+function BlogPostPageMetadata(props: Props): JSX.Element {
+  const {content: BlogPostContents} = props;
+  const {assets, metadata} = BlogPostContents;
+  const {title, description, date, tags, authors, frontMatter} = metadata;
+  const {keywords} = frontMatter;
+  const image = assets.image ?? frontMatter.image;
+  return (
+    <PageMetadata
+      title={title}
+      description={description}
+      keywords={keywords}
+      image={image}>
+      <meta property="og:type" content="article" />
+      <meta property="article:published_time" content={date} />
+      {/* TODO double check those article meta array syntaxes, see https://ogp.me/#array */}
+      {authors.some((author) => author.url) && (
+        <meta
+          property="article:author"
+          content={authors
+            .map((author) => author.url)
+            .filter(Boolean)
+            .join(',')}
+        />
+      )}
+      {tags.length > 0 && (
+        <meta
+          property="article:tag"
+          content={tags.map((tag) => tag.label).join(',')}
+        />
+      )}
+    </PageMetadata>
+  );
+}
+
+function BlogPostPageContent(props: Props): JSX.Element {
   const {content: BlogPostContents, sidebar} = props;
   const {assets, metadata} = BlogPostContents;
-  const {
-    title,
-    description,
-    nextItem,
-    prevItem,
-    date,
-    tags,
-    authors,
-    frontMatter,
-  } = metadata;
+  const {nextItem, prevItem, frontMatter} = metadata;
   const {
     hide_table_of_contents: hideTableOfContents,
-    keywords,
     toc_min_heading_level: tocMinHeadingLevel,
     toc_max_heading_level: tocMaxHeadingLevel,
   } = frontMatter;
-
-  const image = assets.image ?? frontMatter.image;
-
   return (
     <BlogLayout
-      wrapperClassName={ThemeClassNames.wrapper.blogPages}
-      pageClassName={ThemeClassNames.page.blogPostPage}
       sidebar={sidebar}
       toc={
         !hideTableOfContents &&
@@ -52,35 +75,6 @@ export default function BlogPostPage(props: Props): JSX.Element {
           />
         ) : undefined
       }>
-      <Seo
-        // TODO refactor needed: it's a bit annoying but Seo MUST be inside
-        // BlogLayout, otherwise default image (set by BlogLayout) would shadow
-        // the custom blog post image
-        title={title}
-        description={description}
-        keywords={keywords}
-        image={image}>
-        <meta property="og:type" content="article" />
-        <meta property="article:published_time" content={date} />
-
-        {/* TODO double check those article meta array syntaxes, see https://ogp.me/#array */}
-        {authors.some((author) => author.url) && (
-          <meta
-            property="article:author"
-            content={authors
-              .map((author) => author.url)
-              .filter(Boolean)
-              .join(',')}
-          />
-        )}
-        {tags.length > 0 && (
-          <meta
-            property="article:tag"
-            content={tags.map((tag) => tag.label).join(',')}
-          />
-        )}
-      </Seo>
-
       <BlogPostItem
         frontMatter={frontMatter}
         assets={assets}
@@ -95,3 +89,16 @@ export default function BlogPostPage(props: Props): JSX.Element {
     </BlogLayout>
   );
 }
+
+export default function BlogPostPage(props: Props): JSX.Element {
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.blogPages,
+        ThemeClassNames.page.blogPostPage,
+      )}>
+      <BlogPostPageMetadata {...props} />
+      <BlogPostPageContent {...props} />
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/BlogPostPaginator/index.tsx

@@ -21,34 +21,31 @@ export default function BlogPostPaginator(props: Props): JSX.Element {
         message: 'Blog post page navigation',
         description: 'The ARIA label for the blog posts pagination',
       })}>
-      <div className="pagination-nav__item">
-        {prevItem && (
-          <PaginatorNavLink
-            {...prevItem}
-            subLabel={
-              <Translate
-                id="theme.blog.post.paginator.newerPost"
-                description="The blog post button label to navigate to the newer/previous post">
-                Newer Post
-              </Translate>
-            }
-          />
-        )}
-      </div>
-      <div className="pagination-nav__item pagination-nav__item--next">
-        {nextItem && (
-          <PaginatorNavLink
-            {...nextItem}
-            subLabel={
-              <Translate
-                id="theme.blog.post.paginator.olderPost"
-                description="The blog post button label to navigate to the older/next post">
-                Older Post
-              </Translate>
-            }
-          />
-        )}
-      </div>
+      {prevItem && (
+        <PaginatorNavLink
+          {...prevItem}
+          subLabel={
+            <Translate
+              id="theme.blog.post.paginator.newerPost"
+              description="The blog post button label to navigate to the newer/previous post">
+              Newer Post
+            </Translate>
+          }
+        />
+      )}
+      {nextItem && (
+        <PaginatorNavLink
+          {...nextItem}
+          subLabel={
+            <Translate
+              id="theme.blog.post.paginator.olderPost"
+              description="The blog post button label to navigate to the older/next post">
+              Older Post
+            </Translate>
+          }
+          isNext
+        />
+      )}
     </nav>
   );
 }