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

package/src/theme/BlogListPaginator/index.tsx

@@ -10,7 +10,7 @@ import Translate, {translate} from '@docusaurus/Translate';
 import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/BlogListPaginator';
 
-function BlogListPaginator(props: Props): JSX.Element {
+export default function BlogListPaginator(props: Props): JSX.Element {
   const {metadata} = props;
   const {previousPage, nextPage} = metadata;
 
@@ -53,5 +53,3 @@ function BlogListPaginator(props: Props): JSX.Element {
     </nav>
   );
 }
-
-export default BlogListPaginator;

package/src/theme/BlogPostAuthor/index.tsx

@@ -11,7 +11,7 @@ import type {Props} from '@theme/BlogPostAuthor';
 
 import styles from './styles.module.css';
 
-function BlogPostAuthor({author}: Props): JSX.Element {
+export default function BlogPostAuthor({author}: Props): JSX.Element {
   const {name, title, url, imageURL} = author;
   return (
     <div className="avatar margin-bottom--sm">
@@ -21,29 +21,24 @@ function BlogPostAuthor({author}: Props): JSX.Element {
         </Link>
       )}
 
-      {
-        // Note: only legacy author front matter 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>
-            )}
+      {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/src/theme/BlogPostItem/index.tsx

@@ -41,7 +41,7 @@ function useReadingTimePlural() {
   };
 }
 
-function BlogPostItem(props: Props): JSX.Element {
+export default function BlogPostItem(props: Props): JSX.Element {
   const readingTimePlural = useReadingTimePlural();
   const {withBaseUrl} = useBaseUrlUtils();
   const {
@@ -135,7 +135,15 @@ function BlogPostItem(props: Props): JSX.Element {
               })}>
               <Link
                 to={metadata.permalink}
-                aria-label={`Read more about ${title}`}>
+                aria-label={translate(
+                  {
+                    message: 'Read more about {title}',
+                    id: 'theme.blog.post.readMoreLabel',
+                    description:
+                      'The ARIA label for the link to full blog posts from excerpts',
+                  },
+                  {title},
+                )}>
                 <b>
                   <Translate
                     id="theme.blog.post.readMore"
@@ -151,5 +159,3 @@ function BlogPostItem(props: Props): JSX.Element {
     </article>
   );
 }
-
-export default BlogPostItem;

package/src/theme/BlogPostPage/index.tsx

@@ -14,7 +14,7 @@ import type {Props} from '@theme/BlogPostPage';
 import {ThemeClassNames} from '@docusaurus/theme-common';
 import TOC from '@theme/TOC';
 
-function BlogPostPage(props: Props): JSX.Element {
+export default function BlogPostPage(props: Props): JSX.Element {
   const {content: BlogPostContents, sidebar} = props;
   const {assets, metadata} = BlogPostContents;
   const {
@@ -53,8 +53,9 @@ 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
+        // 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}
@@ -94,5 +95,3 @@ function BlogPostPage(props: Props): JSX.Element {
     </BlogLayout>
   );
 }
-
-export default BlogPostPage;

package/src/theme/BlogPostPaginator/index.tsx

@@ -10,7 +10,7 @@ import Translate, {translate} from '@docusaurus/Translate';
 import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/BlogPostPaginator';
 
-function BlogPostPaginator(props: Props): JSX.Element {
+export default function BlogPostPaginator(props: Props): JSX.Element {
   const {nextItem, prevItem} = props;
 
   return (
@@ -52,5 +52,3 @@ function BlogPostPaginator(props: Props): JSX.Element {
     </nav>
   );
 }
-
-export default BlogPostPaginator;

package/src/theme/BlogTagsListPage/index.tsx

@@ -15,7 +15,7 @@ import {
   translateTagsPageTitle,
 } from '@docusaurus/theme-common';
 
-function BlogTagsListPage(props: Props): JSX.Element {
+export default function BlogTagsListPage(props: Props): JSX.Element {
   const {tags, sidebar} = props;
   const title = translateTagsPageTitle();
   return (
@@ -33,5 +33,3 @@ function BlogTagsListPage(props: Props): JSX.Element {
     </BlogLayout>
   );
 }
-
-export default BlogTagsListPage;

package/src/theme/BlogTagsPostsPage/index.tsx

@@ -13,6 +13,7 @@ import BlogPostItem from '@theme/BlogPostItem';
 import type {Props} from '@theme/BlogTagsPostsPage';
 import Translate, {translate} from '@docusaurus/Translate';
 import {ThemeClassNames, usePluralForm} from '@docusaurus/theme-common';
+import BlogListPaginator from '@theme/BlogListPaginator';
 
 // Very simple pluralization: probably good enough for now
 function useBlogPostsPlural() {
@@ -33,7 +34,7 @@ function useBlogPostsPlural() {
 }
 
 export default function BlogTagsPostsPage(props: Props): JSX.Element {
-  const {metadata, items, sidebar} = props;
+  const {metadata, items, sidebar, listMetadata} = props;
   const {allTagsPath, name: tagName, count} = metadata;
   const blogPostsPlural = useBlogPostsPlural();
   const title = translate(
@@ -77,6 +78,7 @@ export default function BlogTagsPostsPage(props: Props): JSX.Element {
           <BlogPostContent />
         </BlogPostItem>
       ))}
+      <BlogListPaginator metadata={listMetadata} />
     </BlogLayout>
   );
 }

package/src/theme/CodeBlock/index.tsx

@@ -51,7 +51,8 @@ export default function CodeBlock({
   const prismTheme = usePrismTheme();
 
   // <pre> tags in markdown map to CodeBlocks and they may contain JSX children.
-  // When the children is not a simple string, we just return a styled block without actually highlighting.
+  // When the children is not a simple string, we just return a styled block
+  // without actually highlighting.
   if (React.Children.toArray(children).some((el) => isValidElement(el))) {
     return (
       <Highlight

package/src/theme/Details/index.tsx

@@ -11,7 +11,8 @@ import {Details as DetailsGeneric} from '@docusaurus/theme-common';
 import type {Props} from '@theme/Details';
 import styles from './styles.module.css';
 
-// Should we have a custom details/summary comp in Infima instead of reusing alert classes?
+// Should we have a custom details/summary comp in Infima instead of reusing
+// alert classes?
 const InfimaClasses = 'alert alert--info';
 
 export default function Details({...props}: Props): JSX.Element {

package/src/theme/DocBreadcrumbs/index.tsx

@@ -0,0 +1,91 @@
+/**
+ * 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, {type ReactNode} from 'react';
+import {
+  ThemeClassNames,
+  useSidebarBreadcrumbs,
+  useHomePageRoute,
+} from '@docusaurus/theme-common';
+import styles from './styles.module.css';
+import clsx from 'clsx';
+import Link from '@docusaurus/Link';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+
+// TODO move to design system folder
+function BreadcrumbsItemLink({
+  children,
+  href,
+}: {
+  children: ReactNode;
+  href?: string;
+}): JSX.Element {
+  const className = clsx('breadcrumbs__link', styles.breadcrumbsItemLink);
+  return href ? (
+    <Link className={className} href={href}>
+      {children}
+    </Link>
+  ) : (
+    <span className={className}>{children}</span>
+  );
+}
+
+// TODO move to design system folder
+function BreadcrumbsItem({
+  children,
+  active,
+}: {
+  children: ReactNode;
+  active?: boolean;
+}): JSX.Element {
+  return (
+    <li
+      className={clsx('breadcrumbs__item', {
+        'breadcrumbs__item--active': active,
+      })}>
+      {children}
+    </li>
+  );
+}
+
+function HomeBreadcrumbItem() {
+  const homeHref = useBaseUrl('/');
+  return (
+    <BreadcrumbsItem>
+      <BreadcrumbsItemLink href={homeHref}>🏠</BreadcrumbsItemLink>
+    </BreadcrumbsItem>
+  );
+}
+
+export default function DocBreadcrumbs(): JSX.Element | null {
+  const breadcrumbs = useSidebarBreadcrumbs();
+  const homePageRoute = useHomePageRoute();
+
+  if (!breadcrumbs) {
+    return null;
+  }
+
+  return (
+    <nav
+      className={clsx(
+        ThemeClassNames.docs.docBreadcrumbs,
+        styles.breadcrumbsContainer,
+      )}
+      aria-label="breadcrumbs">
+      <ul className="breadcrumbs">
+        {homePageRoute && <HomeBreadcrumbItem />}
+        {breadcrumbs.map((item, idx) => (
+          <BreadcrumbsItem key={idx} active={idx === breadcrumbs.length - 1}>
+            <BreadcrumbsItemLink href={item.href}>
+              {item.label}
+            </BreadcrumbsItemLink>
+          </BreadcrumbsItem>
+        ))}
+      </ul>
+    </nav>
+  );
+}

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

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+
+.breadcrumbsContainer {
+  margin-bottom: 0.4rem;
+}
+
+.breadcrumbsItemLink {
+  --ifm-breadcrumb-size-multiplier: 0.7 !important;
+  margin-bottom: 0.4rem;
+  background: var(--ifm-color-gray-100);
+}
+
+html[data-theme='dark'] .breadcrumbsItemLink {
+  background-color: var(--ifm-color-gray-900);
+}
+
+@media (min-width: 997px) {
+  .breadcrumbsItemLink {
+    --ifm-breadcrumb-size-multiplier: 0.8;
+  }
+}

package/src/theme/DocCard/index.tsx

@@ -16,6 +16,7 @@ import {findFirstCategoryLink, useDocById} from '@docusaurus/theme-common';
 import clsx from 'clsx';
 import styles from './styles.module.css';
 import isInternalUrl from '@docusaurus/isInternalUrl';
+import {translate} from '@docusaurus/Translate';
 
 function CardContainer({
   href,
@@ -70,7 +71,15 @@ function CardCategory({item}: {item: PropSidebarItemCategory}): JSX.Element {
       href={href}
       icon="🗃️"
       title={item.label}
-      description={`${item.items.length} items`}
+      description={translate(
+        {
+          message: '{count} items',
+          id: 'theme.docs.DocCard.categoryDescription',
+          description:
+            'The default description for a category card in the generated index about how many items this category includes',
+        },
+        {count: item.items.length},
+      )}
     />
   );
 }

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

@@ -24,7 +24,7 @@
   box-shadow: 0 4px 8px 0 rgb(0 0 0 / 20%);
 }
 
-html[data-theme='dark'] .cardContainer.cardContainerLink:hover {
+[data-theme='dark'] .cardContainer.cardContainerLink:hover {
   --ifm-card-background-color: #2d2d2d; /* original, non-hovered color is #242526 */
 }
 

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -13,6 +13,7 @@ import DocPaginator from '@theme/DocPaginator';
 import Seo from '@theme/Seo';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
 import Heading from '@theme/Heading';
 import useBaseUrl from '@docusaurus/useBaseUrl';
 
@@ -33,6 +34,7 @@ export default function DocCategoryGeneratedIndexPage({
       />
       <div className={styles.generatedIndexPage}>
         <DocVersionBanner />
+        <DocBreadcrumbs />
         <DocVersionBadge />
         <header>
           <Heading as="h1" className={styles.title}>

package/src/theme/DocItem/index.tsx

@@ -18,12 +18,12 @@ import TOCCollapsible from '@theme/TOCCollapsible';
 import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 import {ThemeClassNames, useWindowSize} from '@docusaurus/theme-common';
+import DocBreadcrumbs from '@theme/DocBreadcrumbs';
 
 export default function DocItem(props: Props): JSX.Element {
   const {content: DocContent} = props;
-  const {metadata, frontMatter} = DocContent;
+  const {metadata, frontMatter, assets} = DocContent;
   const {
-    image,
     keywords,
     hide_title: hideTitle,
     hide_table_of_contents: hideTableOfContents,
@@ -31,6 +31,7 @@ export default function DocItem(props: Props): JSX.Element {
     toc_max_heading_level: tocMaxHeadingLevel,
   } = frontMatter;
   const {description, title} = metadata;
+  const image = assets.image ?? frontMatter.image;
 
   // We only add a title if:
   // - user asks to hide it with front matter
@@ -58,6 +59,7 @@ export default function DocItem(props: Props): JSX.Element {
           <DocVersionBanner />
           <div className={styles.docItemContainer}>
             <article>
+              <DocBreadcrumbs />
               <DocVersionBadge />
 
               {canRenderTOC && (
@@ -75,8 +77,9 @@ export default function DocItem(props: Props): JSX.Element {
               <div
                 className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
                 {/*
-                Title can be declared inside md content or declared through front matter and added manually
-                To make both cases consistent, the added title is added under the same div.markdown block
+                Title can be declared inside md content or declared through
+                front matter 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 && (

package/src/theme/DocPage/index.tsx

@@ -145,7 +145,7 @@ function DocPageContent({
   );
 }
 
-function DocPage(props: Props): JSX.Element {
+export default function DocPage(props: Props): JSX.Element {
   const {
     route: {routes: docRoutes},
     versionMetadata,
@@ -168,7 +168,7 @@ function DocPage(props: Props): JSX.Element {
   return (
     <>
       <Head>
-        {/* TODO we should add a core addRoute({htmlClassName}) generic plugin option */}
+        {/* TODO we should add a core addRoute({htmlClassName}) action */}
         <html className={versionMetadata.className} />
       </Head>
       <DocsVersionProvider version={versionMetadata}>
@@ -184,5 +184,3 @@ function DocPage(props: Props): JSX.Element {
     </>
   );
 }
-
-export default DocPage;

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

@@ -69,12 +69,12 @@
     transform: rotate(0);
   }
 
-  html[dir='rtl'] .expandSidebarButtonIcon {
+  [dir='rtl'] .expandSidebarButtonIcon {
     transform: rotate(180deg);
   }
 
-  html[data-theme='dark'] .collapsedDocSidebar:hover,
-  html[data-theme='dark'] .collapsedDocSidebar:focus {
+  [data-theme='dark'] .collapsedDocSidebar:hover,
+  [data-theme='dark'] .collapsedDocSidebar:focus {
     background-color: var(--collapse-button-bg-color-dark);
   }
 

package/src/theme/DocPaginator/index.tsx

@@ -10,7 +10,7 @@ import Translate, {translate} from '@docusaurus/Translate';
 import PaginatorNavLink from '@theme/PaginatorNavLink';
 import type {Props} from '@theme/DocPaginator';
 
-function DocPaginator(props: Props): JSX.Element {
+export default function DocPaginator(props: Props): JSX.Element {
   const {previous, next} = props;
 
   return (
@@ -52,5 +52,3 @@ function DocPaginator(props: Props): JSX.Element {
     </nav>
   );
 }
-
-export default DocPaginator;

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

@@ -72,16 +72,16 @@
     margin-top: 4px;
   }
 
-  html[dir='rtl'] .collapseSidebarButtonIcon {
+  [dir='rtl'] .collapseSidebarButtonIcon {
     transform: rotate(0);
   }
 
-  html[data-theme='dark'] .collapseSidebarButton {
+  [data-theme='dark'] .collapseSidebarButton {
     background-color: var(--collapse-button-bg-color-dark);
   }
 
-  html[data-theme='dark'] .collapseSidebarButton:hover,
-  html[data-theme='dark'] .collapseSidebarButton:focus {
+  [data-theme='dark'] .collapseSidebarButton:hover,
+  [data-theme='dark'] .collapseSidebarButton:focus {
     background-color: var(--ifm-color-emphasis-200);
   }
 }

package/src/theme/DocSidebarItem/index.tsx

@@ -16,6 +16,7 @@ import {
   ThemeClassNames,
   useThemeConfig,
   useDocSidebarItemsExpandedState,
+  isSamePath,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
@@ -31,6 +32,7 @@ import type {
 
 import styles from './styles.module.css';
 import useIsBrowser from '@docusaurus/useIsBrowser';
+import type {SidebarItemHtml} from '@docusaurus/plugin-content-docs/src/sidebars/types';
 
 export default function DocSidebarItem({
   item,
@@ -38,17 +40,17 @@ export default function DocSidebarItem({
 }: Props): JSX.Element | null {
   switch (item.type) {
     case 'category':
-      if (item.items.length === 0) {
-        return null;
-      }
       return <DocSidebarItemCategory item={item} {...props} />;
+    case 'html':
+      return <DocSidebarItemHtml item={item} {...props} />;
     case 'link':
     default:
       return <DocSidebarItemLink item={item} {...props} />;
   }
 }
 
-// If we navigate to a category and it becomes active, it should automatically expand itself
+// If we navigate to a category and it becomes active, it should automatically
+// expand itself
 function useAutoExpandActiveCategory({
   isActive,
   collapsed,
@@ -67,11 +69,14 @@ function useAutoExpandActiveCategory({
   }, [isActive, wasActive, collapsed, setCollapsed]);
 }
 
-// When a collapsible category has no link, we still link it to its first child during SSR as a temporary fallback
-// This allows to be able to navigate inside the category even when JS fails to load, is delayed or simply disabled
-// React hydration becomes an optional progressive enhancement
-// see https://github.com/facebookincubator/infima/issues/36#issuecomment-772543188
-// see https://github.com/facebook/docusaurus/issues/3030
+/**
+ * When a collapsible category has no link, we still link it to its first child
+ * during SSR as a temporary fallback. This allows to be able to navigate inside
+ * the category even when JS fails to load, is delayed or simply disabled
+ * React hydration becomes an optional progressive enhancement
+ * see https://github.com/facebookincubator/infima/issues/36#issuecomment-772543188
+ * see https://github.com/facebook/docusaurus/issues/3030
+ */
 function useCategoryHrefWithSSRFallback(
   item: PropSidebarItemCategory,
 ): string | undefined {
@@ -101,6 +106,7 @@ function DocSidebarItemCategory({
   const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
 
   const isActive = isActiveSidebarItem(item, activePath);
+  const isCurrentPage = isSamePath(href, activePath);
 
   const {collapsed, setCollapsed} = useCollapsible({
     // active categories are always initialized as expanded
@@ -148,13 +154,14 @@ function DocSidebarItemCategory({
         },
         className,
       )}>
-      <div className="menu__list-item-collapsible">
+      <div
+        className={clsx('menu__list-item-collapsible', {
+          'menu__list-item-collapsible--active': isCurrentPage,
+        })}>
         <Link
           className={clsx('menu__link', {
             'menu__link--sublist': collapsible && !href,
             'menu__link--active': isActive,
-            [styles.menuLinkText]: !collapsible,
-            [styles.hasHref]: !!hrefWithSSRFallback,
           })}
           onClick={
             collapsible
@@ -171,7 +178,7 @@ function DocSidebarItemCategory({
                   onItemClick?.(item);
                 }
           }
-          aria-current={isActive ? 'page' : undefined}
+          aria-current={isCurrentPage ? 'page' : undefined}
           href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
           {...props}>
           {label}
@@ -210,6 +217,29 @@ function DocSidebarItemCategory({
   );
 }
 
+function DocSidebarItemHtml({
+  item,
+  level,
+  index,
+}: Props & {item: SidebarItemHtml}) {
+  const {value, defaultStyle, className} = item;
+  return (
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        defaultStyle && `${styles.menuHtmlItem} menu__list-item`,
+        className,
+      )}
+      key={index}
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{
+        __html: value,
+      }}
+    />
+  );
+}
+
 function DocSidebarItemLink({
   item,
   onItemClick,

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

@@ -6,15 +6,8 @@
  */
 
 @media (min-width: 997px) {
-  .menuLinkText {
-    cursor: initial;
-  }
-
-  .menuLinkText:hover {
-    background: none;
-  }
-
-  .menuLinkText.hasHref {
-    cursor: pointer;
+  .menuHtmlItem {
+    padding: var(--ifm-menu-link-padding-vertical)
+      var(--ifm-menu-link-padding-horizontal);
   }
 }

package/src/theme/DocTagsListPage/index.tsx

@@ -15,7 +15,7 @@ import {
 import TagsListByLetter from '@theme/TagsListByLetter';
 import type {Props} from '@theme/DocTagsListPage';
 
-function DocTagsListPage({tags}: Props): JSX.Element {
+export default function DocTagsListPage({tags}: Props): JSX.Element {
   const title = translateTagsPageTitle();
   return (
     <Layout
@@ -37,5 +37,3 @@ function DocTagsListPage({tags}: Props): JSX.Element {
     </Layout>
   );
 }
-
-export default DocTagsListPage;