@docusaurus/theme-classic 2.0.0-beta.8bda3b2db → 2.0.0-beta.9

package/lib-next/theme/BackToTopButton/index.js

@@ -0,0 +1,131 @@
+/**
+ * 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 React, {useRef, useState} from 'react';
+import clsx from 'clsx';
+import {translate} from '@docusaurus/Translate';
+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;
+
+function smoothScrollTopNative() {
+  window.scrollTo({
+    top: 0,
+    behavior: 'smooth',
+  });
+  return () => {
+    // Nothing to cancel, it's natively cancelled if user tries to scroll down
+  };
+}
+
+function smoothScrollTopPolyfill() {
+  let raf = 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);
+}
+
+function useSmoothScrollToTop() {
+  const lastCancelRef = useRef(null);
+
+  function smoothScrollTop() {
+    lastCancelRef.current = SupportsNativeSmoothScrolling
+      ? smoothScrollTopNative()
+      : smoothScrollTopPolyfill();
+  }
+
+  return {
+    smoothScrollTop,
+    cancelScrollToTop: () => lastCancelRef.current?.(),
+  };
+}
+
+function BackToTopButton() {
+  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);
+    }
+  });
+  return (
+    <button
+      aria-label={translate({
+        id: 'theme.BackToTopButton.buttonAriaLabel',
+        message: 'Scroll back to top',
+        description: 'The ARIA label for the back to top button',
+      })}
+      className={clsx(
+        'clean-btn',
+        ThemeClassNames.common.backToTopButton,
+        styles.backToTopButton,
+        {
+          [styles.backToTopButtonShow]: show,
+        },
+      )}
+      type="button"
+      onClick={() => smoothScrollTop()}
+    />
+  );
+}
+
+export default BackToTopButton;

package/lib-next/theme/BackToTopButton/styles.module.css

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+
+.backToTopButton {
+  position: fixed;
+  right: 1.3rem;
+  bottom: 1.3rem;
+  border-radius: 50%;
+  background-color: var(--ifm-color-emphasis-200);
+  width: 3rem;
+  height: 3rem;
+  z-index: var(--ifm-z-index-fixed);
+  box-shadow: var(--ifm-global-shadow-lw);
+  transition: all var(--ifm-transition-fast)
+    var(--ifm-transition-timing-default);
+  opacity: 0;
+  transform: scale(0);
+}
+
+.backToTopButton:after {
+  content: ' ';
+  display: inline-block;
+  mask: var(--ifm-menu-link-sublist-icon) 50% / 2rem 2rem no-repeat;
+  background-color: var(--ifm-color-emphasis-1000);
+  width: 100%;
+  height: 100%;
+}
+
+@media (hover: hover) {
+  .backToTopButton:hover {
+    background-color: var(--ifm-color-emphasis-300);
+  }
+}
+
+.backToTopButtonShow {
+  opacity: 1;
+  transform: scale(1);
+}

package/lib-next/theme/BlogArchivePage/index.js

@@ -0,0 +1,80 @@
+/**
+ * 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 React from 'react';
+import Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import {translate} from '@docusaurus/Translate';
+
+function Year({year, posts}) {
+  return (
+    <>
+      <h3>{year}</h3>
+      <ul>
+        {posts.map((post) => (
+          <li key={post.metadata.date}>
+            <Link to={post.metadata.permalink}>
+              {post.metadata.formattedDate} - {post.metadata.title}
+            </Link>
+          </li>
+        ))}
+      </ul>
+    </>
+  );
+}
+
+function YearsSection({years}) {
+  return (
+    <section className="margin-vert--lg">
+      <div className="container">
+        <div className="row">
+          {years.map((_props, idx) => (
+            <div key={idx} className="col col--4 margin-vert--lg">
+              <Year {..._props} />
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function listPostsByYears(blogPosts) {
+  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());
+  return Array.from(postsByYear, ([year, posts]) => ({
+    year,
+    posts,
+  }));
+}
+
+export default function BlogArchive({archive}) {
+  const title = translate({
+    id: 'theme.blog.archive.title',
+    message: 'Archive',
+    description: 'The page & hero title of the blog archive page',
+  });
+  const description = translate({
+    id: 'theme.blog.archive.description',
+    message: 'Archive',
+    description: 'The page & hero description of the blog archive page',
+  });
+  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>
+  );
+}

package/lib-next/theme/BlogLayout/index.js

@@ -0,0 +1,40 @@
+/**
+ * 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 React from 'react';
+import clsx from 'clsx';
+import Layout from '@theme/Layout';
+import BlogSidebar from '@theme/BlogSidebar';
+
+function BlogLayout(props) {
+  const {sidebar, toc, children, ...layoutProps} = props;
+  const hasSidebar = sidebar && sidebar.items.length > 0;
+  return (
+    <Layout {...layoutProps}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          {hasSidebar && (
+            <aside className="col col--3">
+              <BlogSidebar sidebar={sidebar} />
+            </aside>
+          )}
+          <main
+            className={clsx('col', {
+              'col--7': hasSidebar,
+              'col--9 col--offset-1': !hasSidebar,
+            })}
+            itemScope
+            itemType="http://schema.org/Blog">
+            {children}
+          </main>
+          {toc && <div className="col col--2">{toc}</div>}
+        </div>
+      </div>
+    </Layout>
+  );
+}
+
+export default BlogLayout;

package/lib-next/theme/BlogListPage/index.js

@@ -6,10 +6,9 @@
  */
 import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
-import Layout from '@theme/Layout';
+import BlogLayout from '@theme/BlogLayout';
 import BlogPostItem from '@theme/BlogPostItem';
 import BlogListPaginator from '@theme/BlogListPaginator';
-import BlogSidebar from '@theme/BlogSidebar';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 
 function BlogListPage(props) {
@@ -21,7 +20,7 @@ function BlogListPage(props) {
   const isBlogOnlyMode = permalink === '/';
   const title = isBlogOnlyMode ? siteTitle : blogTitle;
   return (
-    <Layout
+    <BlogLayout
       title={title}
       description={blogDescription}
       wrapperClassName={ThemeClassNames.wrapper.blogPages}
@@ -29,27 +28,20 @@ function BlogListPage(props) {
       searchMetadatas={{
         // assign unique search tag to exclude this page from search results!
         tag: 'blog_posts_list',
-      }}>
-      <div className="container margin-vert--lg">
-        <div className="row">
-          <aside className="col col--3">
-            <BlogSidebar sidebar={sidebar} />
-          </aside>
-          <main className="col col--7">
-            {items.map(({content: BlogPostContent}) => (
-              <BlogPostItem
-                key={BlogPostContent.metadata.permalink}
-                frontMatter={BlogPostContent.frontMatter}
-                metadata={BlogPostContent.metadata}
-                truncated={BlogPostContent.metadata.truncated}>
-                <BlogPostContent />
-              </BlogPostItem>
-            ))}
-            <BlogListPaginator metadata={metadata} />
-          </main>
-        </div>
-      </div>
-    </Layout>
+      }}
+      sidebar={sidebar}>
+      {items.map(({content: BlogPostContent}) => (
+        <BlogPostItem
+          key={BlogPostContent.metadata.permalink}
+          frontMatter={BlogPostContent.frontMatter}
+          assets={BlogPostContent.assets}
+          metadata={BlogPostContent.metadata}
+          truncated={BlogPostContent.metadata.truncated}>
+          <BlogPostContent />
+        </BlogPostItem>
+      ))}
+      <BlogListPaginator metadata={metadata} />
+    </BlogLayout>
   );
 }
 

package/lib-next/theme/BlogPostAuthor/index.js

@@ -0,0 +1,46 @@
+/**
+ * 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 React from 'react';
+import Link from '@docusaurus/Link';
+import styles from './styles.module.css';
+
+function BlogPostAuthor({author}) {
+  const {name, title, url, imageURL} = author;
+  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>
+      )}
+
+      {
+        // Note: only legacy author frontmatter allow empty name (not frontMatter.authors)
+        name && (
+          <div
+            className="avatar__intro"
+            itemProp="author"
+            itemScope
+            itemType="https://schema.org/Person">
+            <div className="avatar__name">
+              <Link href={url} itemProp="url">
+                <span itemProp="name">{name}</span>
+              </Link>
+            </div>
+            {title && (
+              <small className="avatar__subtitle" itemProp="description">
+                {title}
+              </small>
+            )}
+          </div>
+        )
+      }
+    </div>
+  );
+}
+
+export default BlogPostAuthor;

package/lib-next/theme/BlogPostAuthor/styles.module.css

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+.image {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+}

package/lib-next/theme/BlogPostAuthors/index.js

@@ -0,0 +1,34 @@
+/**
+ * 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 React from 'react';
+import clsx from 'clsx';
+import BlogPostAuthor from '@theme/BlogPostAuthor';
+import styles from './styles.module.css'; // Component responsible for the authors layout
+
+export default function BlogPostAuthors({authors, assets}) {
+  const authorsCount = authors.length;
+
+  if (authorsCount === 0) {
+    return <></>;
+  }
+
+  return (
+    <div className="row margin-top--md margin-bottom--sm">
+      {authors.map((author, idx) => (
+        <div className={clsx('col col--6', styles.authorCol)} key={idx}>
+          <BlogPostAuthor
+            author={{
+              ...author,
+              // Handle author images using relative paths
+              imageURL: assets.authorsImageUrls[idx] ?? author.imageURL,
+            }}
+          />
+        </div>
+      ))}
+    </div>
+  );
+}

package/lib-next/theme/BlogPostAuthors/styles.module.css

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+
+.authorCol {
+  max-width: inherit !important;
+  flex-grow: 1 !important;
+}

package/lib-next/theme/BlogPostItem/index.js

@@ -9,11 +9,13 @@ 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 MDXComponents from '@theme/MDXComponents';
-import Seo from '@theme/Seo';
 import EditThisPage from '@theme/EditThisPage';
-import styles from './styles.module.css'; // Very simple pluralization: probably good enough for now
+import styles from './styles.module.css';
+import TagsListInline from '@theme/TagsListInline';
+import BlogPostAuthors from '@theme/BlogPostAuthors'; // Very simple pluralization: probably good enough for now
 
 function useReadingTimePlural() {
   const {selectMessage} = usePluralForm();
@@ -38,9 +40,11 @@ function useReadingTimePlural() {
 
 function BlogPostItem(props) {
   const readingTimePlural = useReadingTimePlural();
+  const {withBaseUrl} = useBaseUrlUtils();
   const {
     children,
     frontMatter,
+    assets,
     metadata,
     truncated,
     isBlogPostPage = false,
@@ -53,115 +57,104 @@ function BlogPostItem(props) {
     readingTime,
     title,
     editUrl,
+    authors,
   } = metadata;
-  const {author, image, keywords} = frontMatter;
-  const authorURL = frontMatter.author_url || frontMatter.authorURL;
-  const authorTitle = frontMatter.author_title || frontMatter.authorTitle;
-  const authorImageURL =
-    frontMatter.author_image_url || frontMatter.authorImageURL;
+  const image = assets.image ?? frontMatter.image;
+  const truncatedPost = !isBlogPostPage && truncated;
+  const tagsExists = tags.length > 0;
 
   const renderPostHeader = () => {
     const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
     return (
       <header>
-        <TitleHeading className={styles.blogPostTitle}>
-          {isBlogPostPage ? title : <Link to={permalink}>{title}</Link>}
+        <TitleHeading className={styles.blogPostTitle} itemProp="headline">
+          {isBlogPostPage ? (
+            title
+          ) : (
+            <Link itemProp="url" to={permalink}>
+              {title}
+            </Link>
+          )}
         </TitleHeading>
         <div className={clsx(styles.blogPostData, 'margin-vert--md')}>
-          <time dateTime={date}>{formattedDate}</time>
+          <time dateTime={date} itemProp="datePublished">
+            {formattedDate}
+          </time>
 
-          {readingTime && (
+          {typeof readingTime !== 'undefined' && (
             <>
               {' · '}
               {readingTimePlural(readingTime)}
             </>
           )}
         </div>
-        <div className="avatar margin-vert--md">
-          {authorImageURL && (
-            <Link className="avatar__photo-link avatar__photo" href={authorURL}>
-              <img src={authorImageURL} alt={author} />
-            </Link>
-          )}
-          <div className="avatar__intro">
-            {author && (
-              <>
-                <div className="avatar__name">
-                  <Link href={authorURL}>{author}</Link>
-                </div>
-                <small className="avatar__subtitle">{authorTitle}</small>
-              </>
-            )}
-          </div>
-        </div>
+        <BlogPostAuthors authors={authors} assets={assets} />
       </header>
     );
   };
 
   return (
-    <>
-      <Seo
-        {...{
-          keywords,
-          image,
-        }}
-      />
+    <article
+      className={!isBlogPostPage ? 'margin-bottom--xl' : undefined}
+      itemProp="blogPost"
+      itemScope
+      itemType="http://schema.org/BlogPosting">
+      {renderPostHeader()}
 
-      <article className={!isBlogPostPage ? 'margin-bottom--xl' : undefined}>
-        {renderPostHeader()}
-        <div className="markdown">
-          <MDXProvider components={MDXComponents}>{children}</MDXProvider>
-        </div>
-        {(tags.length > 0 || truncated) && (
-          <footer
-            className={clsx('row docusaurus-mt-lg', {
-              [styles.blogPostDetailsFull]: isBlogPostPage,
-            })}>
-            {tags.length > 0 && (
-              <div className="col">
+      {image && (
+        <meta
+          itemProp="image"
+          content={withBaseUrl(image, {
+            absolute: true,
+          })}
+        />
+      )}
+
+      <div className="markdown" itemProp="articleBody">
+        <MDXProvider components={MDXComponents}>{children}</MDXProvider>
+      </div>
+
+      {(tagsExists || truncated) && (
+        <footer
+          className={clsx('row docusaurus-mt-lg', {
+            [styles.blogPostDetailsFull]: isBlogPostPage,
+          })}>
+          {tagsExists && (
+            <div
+              className={clsx('col', {
+                'col--9': truncatedPost,
+              })}>
+              <TagsListInline tags={tags} />
+            </div>
+          )}
+
+          {isBlogPostPage && editUrl && (
+            <div className="col margin-top--sm">
+              <EditThisPage editUrl={editUrl} />
+            </div>
+          )}
+
+          {truncatedPost && (
+            <div
+              className={clsx('col text--right', {
+                'col--3': tagsExists,
+              })}>
+              <Link
+                to={metadata.permalink}
+                aria-label={`Read more about ${title}`}>
                 <b>
                   <Translate
-                    id="theme.tags.tagsListLabel"
-                    description="The label alongside a tag list">
-                    Tags:
+                    id="theme.blog.post.readMore"
+                    description="The label used in blog post item excerpts to link to full blog posts">
+                    Read More
                   </Translate>
                 </b>
-                {tags.map(({label, permalink: tagPermalink}) => (
-                  <Link
-                    key={tagPermalink}
-                    className="margin-horiz--sm"
-                    to={tagPermalink}>
-                    {label}
-                  </Link>
-                ))}
-              </div>
-            )}
-
-            {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}`}>
-                  <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>
-                  </b>
-                </Link>
-              </div>
-            )}
-          </footer>
-        )}
-      </article>
-    </>
+              </Link>
+            </div>
+          )}
+        </footer>
+      )}
+    </article>
   );
 }