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

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

@@ -11,6 +11,7 @@ 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 EditThisPage from '@theme/EditThisPage';
 import styles from './styles.module.css';
@@ -62,10 +63,13 @@ function BlogPostItem(props) {
   const image = assets.image ?? frontMatter.image;
   const truncatedPost = !isBlogPostPage && truncated;
   const tagsExists = tags.length > 0;
-
-  const renderPostHeader = () => {
-    const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
-    return (
+  const TitleHeading = isBlogPostPage ? 'h1' : 'h2';
+  return (
+    <article
+      className={!isBlogPostPage ? 'margin-bottom--xl' : undefined}
+      itemProp="blogPost"
+      itemScope
+      itemType="http://schema.org/BlogPosting">
       <header>
         <TitleHeading className={styles.blogPostTitle} itemProp="headline">
           {isBlogPostPage ? (
@@ -90,16 +94,6 @@ function BlogPostItem(props) {
         </div>
         <BlogPostAuthors authors={authors} assets={assets} />
       </header>
-    );
-  };
-
-  return (
-    <article
-      className={!isBlogPostPage ? 'margin-bottom--xl' : undefined}
-      itemProp="blogPost"
-      itemScope
-      itemType="http://schema.org/BlogPosting">
-      {renderPostHeader()}
 
       {image && (
         <meta
@@ -110,7 +104,10 @@ function BlogPostItem(props) {
         />
       )}
 
-      <div className="markdown" itemProp="articleBody">
+      <div // This ID is used for the feed generation to locate the main content
+        id={isBlogPostPage ? blogPostContainerID : undefined}
+        className="markdown"
+        itemProp="articleBody">
         <MDXProvider components={MDXComponents}>{children}</MDXProvider>
       </div>
 

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

@@ -14,14 +14,17 @@ import TOC from '@theme/TOC';
 
 function BlogPostPage(props) {
   const {content: BlogPostContents, sidebar} = props;
+  const {assets, metadata} = BlogPostContents;
   const {
-    // TODO this frontmatter is not validated/normalized, it's the raw user-provided one. We should expose normalized one too!
+    title,
+    description,
+    nextItem,
+    prevItem,
+    date,
+    tags,
+    authors,
     frontMatter,
-    assets,
-    metadata,
-  } = BlogPostContents;
-  const {title, description, nextItem, prevItem, date, tags, authors} =
-    metadata;
+  } = metadata;
   const {
     hide_table_of_contents: hideTableOfContents,
     keywords,
@@ -54,7 +57,7 @@ function BlogPostPage(props) {
         <meta property="og:type" content="article" />
         <meta property="article:published_time" content={date} />
 
-        {/* TODO double check those article metas array syntaxes, see https://ogp.me/#array */}
+        {/* TODO double check those article meta array syntaxes, see https://ogp.me/#array */}
         {authors.some((author) => author.url) && (
           <meta
             property="article:author"

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

@@ -6,7 +6,7 @@
  */
 import React from 'react';
 import Translate, {translate} from '@docusaurus/Translate';
-import Link from '@docusaurus/Link';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
 
 function BlogPostPaginator(props) {
   const {nextItem, prevItem} = props;
@@ -20,34 +20,30 @@ function BlogPostPaginator(props) {
       })}>
       <div className="pagination-nav__item">
         {prevItem && (
-          <Link className="pagination-nav__link" to={prevItem.permalink}>
-            <div className="pagination-nav__sublabel">
+          <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__label">
-              &laquo; {prevItem.title}
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
         {nextItem && (
-          <Link className="pagination-nav__link" to={nextItem.permalink}>
-            <div className="pagination-nav__sublabel">
+          <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>
-            <div className="pagination-nav__label">
-              {nextItem.title} &raquo;
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
     </nav>

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

@@ -30,9 +30,11 @@
 .sidebarItemLink {
   color: var(--ifm-font-color-base);
 }
+
 .sidebarItemLink:hover {
   text-decoration: none;
 }
+
 .sidebarItemLinkActive {
   color: var(--ifm-color-primary) !important;
 }

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

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {useEffect, useState} from 'react';
+import React, {isValidElement, useEffect, useState} from 'react';
 import clsx from 'clsx';
 import Highlight, {defaultProps} from 'prism-react-renderer';
 import copy from 'copy-text-to-clipboard';
@@ -15,14 +15,15 @@ import {
   parseLanguage,
   parseLines,
   ThemeClassNames,
+  usePrismTheme,
 } from '@docusaurus/theme-common';
-import usePrismTheme from '@theme/hooks/usePrismTheme';
 import styles from './styles.module.css';
 export default function CodeBlock({
   children,
-  className: blockClassName,
+  className: blockClassName = '',
   metastring,
   title,
+  language: languageProp,
 }) {
   const {prism} = useThemeConfig();
   const [showCopied, setShowCopied] = useState(false);
@@ -36,15 +37,45 @@ export default function CodeBlock({
 
   useEffect(() => {
     setMounted(true);
-  }, []); // TODO: the title is provided by MDX as props automatically
-  // so we probably don't need to parse the metastring
-  // (note: title="xyz" => title prop still has the quotes)
+  }, []); // We still parse the metastring in case we want to support more syntax in the
+  // future. Note that MDX doesn't strip quotes when parsing metastring:
+  // "title=\"xyz\"" => title: "\"xyz\""
 
   const codeBlockTitle = parseCodeBlockTitle(metastring) || title;
-  const prismTheme = usePrismTheme(); // In case interleaved Markdown (e.g. when using CodeBlock as standalone component).
+  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.
+
+  if (React.Children.toArray(children).some((el) => isValidElement(el))) {
+    return (
+      <Highlight
+        {...defaultProps}
+        key={String(mounted)}
+        theme={prismTheme}
+        code=""
+        language={'text'}>
+        {({className, style}) => (
+          <pre
+            /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
+            tabIndex={0}
+            className={clsx(
+              className,
+              styles.codeBlockStandalone,
+              'thin-scrollbar',
+              styles.codeBlockContainer,
+              blockClassName,
+              ThemeClassNames.common.codeBlock,
+            )}
+            style={style}>
+            <code className={styles.codeBlockLines}>{children}</code>
+          </pre>
+        )}
+      </Highlight>
+    );
+  } // The children is now guaranteed to be one/more plain strings
 
   const content = Array.isArray(children) ? children.join('') : children;
-  const language = parseLanguage(blockClassName) ?? prism.defaultLanguage;
+  const language =
+    languageProp ?? parseLanguage(blockClassName) ?? prism.defaultLanguage;
   const {highlightLines, code} = parseLines(content, metastring, language);
 
   const handleCopyCode = () => {
@@ -59,12 +90,16 @@ export default function CodeBlock({
       key={String(mounted)}
       theme={prismTheme}
       code={code}
-      language={language}>
+      language={language ?? 'text'}>
       {({className, style, tokens, getLineProps, getTokenProps}) => (
         <div
           className={clsx(
             styles.codeBlockContainer,
             blockClassName,
+            {
+              [`language-${language}`]:
+                language && !blockClassName.includes(`language-${language}`),
+            },
             ThemeClassNames.common.codeBlock,
           )}>
           {codeBlockTitle && (

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

@@ -13,7 +13,7 @@
 
 .codeBlockContent {
   position: relative;
-  /*rtl:ignore*/
+  /* rtl:ignore */
   direction: ltr;
 }
 
@@ -26,19 +26,24 @@
   border-top-right-radius: var(--ifm-global-radius);
 }
 
+.codeBlock {
+  margin: 0;
+  padding: 0;
+  border-radius: var(--ifm-global-radius);
+}
+
 .codeBlockTitle + .codeBlockContent .codeBlock {
   border-top-left-radius: 0;
   border-top-right-radius: 0;
 }
 
-.codeBlock {
-  margin: 0;
+.codeBlockStandalone {
   padding: 0;
   border-radius: var(--ifm-global-radius);
 }
 
 .copyButton {
-  background: rgba(0, 0, 0, 0.3);
+  background: rgb(0 0 0 / 30%);
   border-radius: var(--ifm-global-radius);
   color: var(--ifm-color-white);
   opacity: 0;
@@ -50,15 +55,15 @@
   transition: opacity 200ms ease-in-out;
 }
 
-.codeBlockTitle:hover + .codeBlockContent .copyButton,
+.copyButton:focus,
 .codeBlockContent:hover > .copyButton,
-.copyButton:focus {
+.codeBlockTitle:hover + .codeBlockContent .copyButton {
   opacity: 1;
 }
 
 .codeBlockLines {
   font: inherit;
-  /*rtl:ignore*/
+  /* rtl:ignore */
   float: left;
   min-width: 100%;
   padding: var(--ifm-pre-padding);

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

@@ -7,14 +7,13 @@
 
 .cardContainer {
   height: 8rem;
-
   color: var(--ifm-color-emphasis-800);
   --ifm-link-color: var(--ifm-color-emphasis-800);
   --ifm-link-hover-color: var(--ifm-color-emphasis-800);
   --ifm-link-hover-decoration: none;
 
   /* box-shadow: var(--ifm-global-shadow-lw); */
-  box-shadow: 0 1.5px 3px 0 rgba(0, 0, 0, 0.15);
+  box-shadow: 0 1.5px 3px 0 rgb(0 0 0 / 15%);
   border: 1px solid var(--ifm-color-emphasis-200);
   transition: box-shadow var(--ifm-transition-fast) ease,
     background-color var(--ifm-transition-fast) ease;
@@ -22,8 +21,9 @@
 
 .cardContainer.cardContainerLink:hover {
   /* box-shadow: var(--ifm-global-shadow-md); */
-  box-shadow: 0 4px 8px 0 rgba(0, 0, 0, 0.2);
+  box-shadow: 0 4px 8px 0 rgb(0 0 0 / 20%);
 }
+
 html[data-theme='dark'] .cardContainer.cardContainerLink:hover {
   --ifm-card-background-color: #2d2d2d; /* original, non-hovered color is #242526 */
 }

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

@@ -11,7 +11,8 @@ import DocPaginator from '@theme/DocPaginator';
 import Seo from '@theme/Seo';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';
-import {MainHeading} from '@theme/Heading';
+import Heading from '@theme/Heading';
+import useBaseUrl from '@docusaurus/useBaseUrl';
 import styles from './styles.module.css';
 export default function DocCategoryGeneratedIndexPage({
   categoryGeneratedIndex,
@@ -22,14 +23,16 @@ export default function DocCategoryGeneratedIndexPage({
       <Seo
         title={categoryGeneratedIndex.title}
         description={categoryGeneratedIndex.description}
+        keywords={categoryGeneratedIndex.keywords} // TODO `require` this?
+        image={useBaseUrl(categoryGeneratedIndex.image)}
       />
       <div className={styles.generatedIndexPage}>
         <DocVersionBanner />
         <DocVersionBadge />
         <header>
-          <MainHeading className={styles.title}>
+          <Heading as="h1" className={styles.title}>
             {categoryGeneratedIndex.title}
-          </MainHeading>
+          </Heading>
           {categoryGeneratedIndex.description && (
             <p>{categoryGeneratedIndex.description}</p>
           )}

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

@@ -6,7 +6,6 @@
  */
 import React from 'react';
 import clsx from 'clsx';
-import useWindowSize from '@theme/hooks/useWindowSize';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import DocVersionBadge from '@theme/DocVersionBadge';
@@ -14,9 +13,9 @@ import Seo from '@theme/Seo';
 import DocItemFooter from '@theme/DocItemFooter';
 import TOC from '@theme/TOC';
 import TOCCollapsible from '@theme/TOCCollapsible';
-import {MainHeading} from '@theme/Heading';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
-import {ThemeClassNames} from '@docusaurus/theme-common';
+import {ThemeClassNames, useWindowSize} from '@docusaurus/theme-common';
 export default function DocItem(props) {
   const {content: DocContent} = props;
   const {metadata, frontMatter} = DocContent;
@@ -29,7 +28,7 @@ export default function DocItem(props) {
     toc_max_heading_level: tocMaxHeadingLevel,
   } = frontMatter;
   const {description, title} = metadata; // We only add a title if:
-  // - user asks to hide it with frontmatter
+  // - user asks to hide it with front matter
   // - the markdown content does not already contain a top-level h1 heading
 
   const shouldAddTitle =
@@ -75,11 +74,15 @@ export default function DocItem(props) {
               <div
                 className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
                 {/*
-                Title can be declared inside md content or declared through frontmatter and added manually
+                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 && <MainHeading>{title}</MainHeading>}
+                {shouldAddTitle && (
+                  <header>
+                    <Heading as="h1">{title}</Heading>
+                  </header>
+                )}
 
                 <DocContent />
               </div>

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

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docItemContainer article > *:first-child,
-.docItemContainer header + * {
+.docItemContainer header + *,
+.docItemContainer article > *:first-child {
   margin-top: 0;
 }
 

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

@@ -56,9 +56,13 @@ function DocPageContent({
 
         {sidebar && (
           <aside
-            className={clsx(styles.docSidebarContainer, {
-              [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
-            })}
+            className={clsx(
+              ThemeClassNames.docs.docSidebarContainer,
+              styles.docSidebarContainer,
+              {
+                [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
+              },
+            )}
             onTransitionEnd={(e) => {
               if (
                 !e.currentTarget.classList.contains(styles.docSidebarContainer)

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

@@ -68,6 +68,7 @@
   .expandSidebarButtonIcon {
     transform: rotate(0);
   }
+
   html[dir='rtl'] .expandSidebarButtonIcon {
     transform: rotate(180deg);
   }

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

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import {translate} from '@docusaurus/Translate';
-import DocPaginatorNavLink from '@theme/DocPaginatorNavLink';
+import Translate, {translate} from '@docusaurus/Translate';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
 
 function DocPaginator(props) {
   const {previous, next} = props;
@@ -19,10 +19,32 @@ function DocPaginator(props) {
         description: 'The ARIA label for the docs pagination',
       })}>
       <div className="pagination-nav__item">
-        {previous && <DocPaginatorNavLink navLink={previous} />}
+        {previous && (
+          <PaginatorNavLink
+            {...previous}
+            subLabel={
+              <Translate
+                id="theme.docs.paginator.previous"
+                description="The label used to navigate to the previous doc">
+                Previous
+              </Translate>
+            }
+          />
+        )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
-        {next && <DocPaginatorNavLink navLink={next} next />}
+        {next && (
+          <PaginatorNavLink
+            {...next}
+            subLabel={
+              <Translate
+                id="theme.docs.paginator.next"
+                description="The label used to navigate to the next doc">
+                Next
+              </Translate>
+            }
+          />
+        )}
       </div>
     </nav>
   );

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

@@ -12,12 +12,12 @@ import {
   MobileSecondaryMenuFiller,
   ThemeClassNames,
   useScrollPosition,
+  useWindowSize,
 } from '@docusaurus/theme-common';
-import useWindowSize from '@theme/hooks/useWindowSize';
 import Logo from '@theme/Logo';
 import IconArrow from '@theme/IconArrow';
 import {translate} from '@docusaurus/Translate';
-import {DocSidebarItems} from '@theme/DocSidebarItem';
+import DocSidebarItems from '@theme/DocSidebarItems';
 import styles from './styles.module.css';
 
 function useShowAnnouncementBar() {

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

@@ -71,6 +71,7 @@
     transform: rotate(180deg);
     margin-top: 4px;
   }
+
   html[dir='rtl'] .collapseSidebarButtonIcon {
     transform: rotate(0);
   }

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

@@ -4,7 +4,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {useEffect, memo, useMemo} from 'react';
+import React, {useEffect, useMemo} from 'react';
 import clsx from 'clsx';
 import {
   isActiveSidebarItem,
@@ -13,27 +13,16 @@ import {
   useCollapsible,
   findFirstCategoryLink,
   ThemeClassNames,
+  useThemeConfig,
+  useDocSidebarItemsExpandedState,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
 import {translate} from '@docusaurus/Translate';
 import IconExternalLink from '@theme/IconExternalLink';
+import DocSidebarItems from '@theme/DocSidebarItems';
 import styles from './styles.module.css';
-import useIsBrowser from '@docusaurus/useIsBrowser'; // Optimize sidebar at each "level"
-// TODO this item should probably not receive the "activePath" props
-// TODO this triggers whole sidebar re-renders on navigation
-
-export const DocSidebarItems = memo(({items, ...props}) => (
-  <>
-    {items.map((item, index) => (
-      <DocSidebarItem
-        key={index} // sidebar is static, the index does not change
-        item={item}
-        {...props}
-      />
-    ))}
-  </>
-));
+import useIsBrowser from '@docusaurus/useIsBrowser';
 export default function DocSidebarItem({item, ...props}) {
   switch (item.type) {
     case 'category':
@@ -85,12 +74,13 @@ function DocSidebarItemCategory({
   onItemClick,
   activePath,
   level,
+  index,
   ...props
 }) {
   const {items, label, collapsible, className, href} = item;
   const hrefWithSSRFallback = useCategoryHrefWithSSRFallback(item);
   const isActive = isActiveSidebarItem(item, activePath);
-  const {collapsed, setCollapsed, toggleCollapsed} = useCollapsible({
+  const {collapsed, setCollapsed} = useCollapsible({
     // active categories are always initialized as expanded
     // the default (item.collapsed) is only used for non-active categories
     initialState: () => {
@@ -106,6 +96,30 @@ function DocSidebarItemCategory({
     collapsed,
     setCollapsed,
   });
+  const {expandedItem, setExpandedItem} = useDocSidebarItemsExpandedState();
+
+  function updateCollapsed(toCollapsed = !collapsed) {
+    setExpandedItem(toCollapsed ? null : index);
+    setCollapsed(toCollapsed);
+  }
+
+  const {autoCollapseSidebarCategories} = useThemeConfig();
+  useEffect(() => {
+    if (
+      collapsible &&
+      expandedItem &&
+      expandedItem !== index &&
+      autoCollapseSidebarCategories
+    ) {
+      setCollapsed(true);
+    }
+  }, [
+    collapsible,
+    expandedItem,
+    index,
+    setCollapsed,
+    autoCollapseSidebarCategories,
+  ]);
   return (
     <li
       className={clsx(
@@ -131,16 +145,17 @@ function DocSidebarItemCategory({
                   onItemClick?.(item);
 
                   if (href) {
-                    setCollapsed(false);
+                    updateCollapsed(false);
                   } else {
                     e.preventDefault();
-                    toggleCollapsed();
+                    updateCollapsed();
                   }
                 }
               : () => {
                   onItemClick?.(item);
                 }
           }
+          aria-current={isActive ? 'page' : undefined}
           href={collapsible ? hrefWithSSRFallback ?? '#' : hrefWithSSRFallback}
           {...props}>
           {label}
@@ -162,7 +177,7 @@ function DocSidebarItemCategory({
             className="clean-btn menu__caret"
             onClick={(e) => {
               e.preventDefault();
-              toggleCollapsed();
+              updateCollapsed();
             }}
           />
         )}
@@ -181,7 +196,14 @@ function DocSidebarItemCategory({
   );
 }
 
-function DocSidebarItemLink({item, onItemClick, activePath, level, ...props}) {
+function DocSidebarItemLink({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  index,
+  ...props
+}) {
   const {href, label, className} = item;
   const isActive = isActiveSidebarItem(item, activePath);
   return (

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

@@ -9,6 +9,7 @@
   .menuLinkText {
     cursor: initial;
   }
+
   .menuLinkText:hover {
     background: none;
   }