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

package/src/theme/CodeBlock/index.tsx

@@ -5,9 +5,9 @@
  * 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, Language} from 'prism-react-renderer';
+import Highlight, {defaultProps, type Language} from 'prism-react-renderer';
 import copy from 'copy-text-to-clipboard';
 import Translate, {translate} from '@docusaurus/Translate';
 import {
@@ -15,17 +15,19 @@ import {
   parseCodeBlockTitle,
   parseLanguage,
   parseLines,
+  ThemeClassNames,
+  usePrismTheme,
 } from '@docusaurus/theme-common';
-import usePrismTheme from '@theme/hooks/usePrismTheme';
 import type {Props} from '@theme/CodeBlock';
 
 import styles from './styles.module.css';
 
 export default function CodeBlock({
   children,
-  className: blockClassName,
+  className: blockClassName = '',
   metastring,
   title,
+  language: languageProp,
 }: Props): JSX.Element {
   const {prism} = useThemeConfig();
 
@@ -42,19 +44,49 @@ export default function CodeBlock({
     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).
+  // <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' as Language}>
+        {({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 as string);
 
   const language =
-    parseLanguage(blockClassName) ?? (prism.defaultLanguage as Language);
+    languageProp ?? parseLanguage(blockClassName) ?? prism.defaultLanguage;
   const {highlightLines, code} = parseLines(content, metastring, language);
 
   const handleCopyCode = () => {
@@ -70,9 +102,18 @@ export default function CodeBlock({
       key={String(mounted)}
       theme={prismTheme}
       code={code}
-      language={language}>
+      language={(language ?? 'text') as Language}>
       {({className, style, tokens, getLineProps, getTokenProps}) => (
-        <div className={clsx(styles.codeBlockContainer, blockClassName)}>
+        <div
+          className={clsx(
+            styles.codeBlockContainer,
+            blockClassName,
+            {
+              [`language-${language}`]:
+                language && !blockClassName.includes(`language-${language}`),
+            },
+            ThemeClassNames.common.codeBlock,
+          )}>
           {codeBlockTitle && (
             <div style={style} className={styles.codeBlockTitle}>
               {codeBlockTitle}

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

@@ -9,12 +9,11 @@
   margin-bottom: var(--ifm-leading);
   border-radius: var(--ifm-global-radius);
   box-shadow: var(--ifm-global-shadow-lw);
-  overflow: hidden;
 }
 
 .codeBlockContent {
   position: relative;
-  /*rtl:ignore*/
+  /* rtl:ignore */
   direction: ltr;
 }
 
@@ -23,16 +22,28 @@
   font-size: var(--ifm-code-font-size);
   font-weight: 500;
   padding: 0.75rem var(--ifm-pre-padding);
+  border-top-left-radius: var(--ifm-global-radius);
+  border-top-right-radius: var(--ifm-global-radius);
 }
 
 .codeBlock {
   margin: 0;
   padding: 0;
-  border-radius: 0;
+  border-radius: var(--ifm-global-radius);
+}
+
+.codeBlockTitle + .codeBlockContent .codeBlock {
+  border-top-left-radius: 0;
+  border-top-right-radius: 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;
@@ -44,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/src/theme/DocCard/index.tsx

@@ -5,9 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ReactNode} from 'react';
+import React, {type ReactNode} from 'react';
 import Link from '@docusaurus/Link';
-import {
+import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
 } from '@docusaurus/plugin-content-docs';

package/src/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/src/theme/DocCardList/index.tsx

@@ -8,7 +8,7 @@
 import React from 'react';
 
 import DocCard from '@theme/DocCard';
-import {PropSidebarItem} from '@docusaurus/plugin-content-docs';
+import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 
 export default function DocCardList({
   items,

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -13,7 +13,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';
 
@@ -26,14 +27,17 @@ 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/src/theme/DocItem/index.tsx

@@ -7,7 +7,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';
@@ -16,9 +15,9 @@ import type {Props} from '@theme/DocItem';
 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: Props): JSX.Element {
   const {content: DocContent} = props;
@@ -34,7 +33,7 @@ export default function DocItem(props: Props): JSX.Element {
   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 =
     !hideTitle && typeof DocContent.contentTitle === 'undefined';
@@ -76,11 +75,15 @@ 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 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/src/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/src/theme/DocItemFooter/index.tsx

@@ -12,7 +12,7 @@ import LastUpdated from '@theme/LastUpdated';
 import type {Props} from '@theme/DocItem';
 import EditThisPage from '@theme/EditThisPage';
 import TagsListInline, {
-  Props as TagsListInlineProps,
+  type Props as TagsListInlineProps,
 } from '@theme/TagsListInline';
 
 import styles from './styles.module.css';

package/src/theme/DocPage/index.tsx

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ReactNode, useState, useCallback} from 'react';
+import React, {type ReactNode, useState, useCallback} from 'react';
 import {MDXProvider} from '@mdx-js/react';
 
 import renderRoutes from '@docusaurus/renderRoutes';
@@ -70,9 +70,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/src/theme/DocPage/styles.module.css

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

package/src/theme/DocPaginator/index.tsx

@@ -6,11 +6,11 @@
  */
 
 import React from 'react';
-import Link from '@docusaurus/Link';
 import Translate, {translate} from '@docusaurus/Translate';
-import type {PropNavigation} from '@docusaurus/plugin-content-docs';
+import PaginatorNavLink from '@theme/PaginatorNavLink';
+import type {Props} from '@theme/DocPaginator';
 
-function DocPaginator(props: PropNavigation): JSX.Element {
+function DocPaginator(props: Props): JSX.Element {
   const {previous, next} = props;
 
   return (
@@ -23,32 +23,30 @@ function DocPaginator(props: PropNavigation): JSX.Element {
       })}>
       <div className="pagination-nav__item">
         {previous && (
-          <Link className="pagination-nav__link" to={previous.permalink}>
-            <div className="pagination-nav__sublabel">
+          <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__label">
-              &laquo; {previous.title}
-            </div>
-          </Link>
+            }
+          />
         )}
       </div>
       <div className="pagination-nav__item pagination-nav__item--next">
         {next && (
-          <Link className="pagination-nav__link" to={next.permalink}>
-            <div className="pagination-nav__sublabel">
+          <PaginatorNavLink
+            {...next}
+            subLabel={
               <Translate
                 id="theme.docs.paginator.next"
                 description="The label used to navigate to the next doc">
                 Next
               </Translate>
-            </div>
-            <div className="pagination-nav__label">{next.title} &raquo;</div>
-          </Link>
+            }
+          />
         )}
       </div>
     </nav>

package/src/theme/DocSidebar/index.tsx

@@ -11,15 +11,15 @@ import {
   useThemeConfig,
   useAnnouncementBar,
   MobileSecondaryMenuFiller,
-  MobileSecondaryMenuComponent,
+  type MobileSecondaryMenuComponent,
   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 type {Props} from '@theme/DocSidebar';
 
 import styles from './styles.module.css';

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

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

package/src/theme/DocSidebarItem/index.tsx

@@ -5,7 +5,7 @@
  * 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,
@@ -14,13 +14,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 type {Props, DocSidebarItemsProps} from '@theme/DocSidebarItem';
+import DocSidebarItems from '@theme/DocSidebarItems';
+import type {Props} from '@theme/DocSidebarItem';
 import type {
   PropSidebarItemCategory,
   PropSidebarItemLink,
@@ -29,23 +32,6 @@ import type {
 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}: DocSidebarItemsProps): JSX.Element => (
-    <>
-      {items.map((item, index) => (
-        <DocSidebarItem
-          key={index} // sidebar is static, the index does not change
-          item={item}
-          {...props}
-        />
-      ))}
-    </>
-  ),
-);
-
 export default function DocSidebarItem({
   item,
   ...props
@@ -108,6 +94,7 @@ function DocSidebarItemCategory({
   onItemClick,
   activePath,
   level,
+  index,
   ...props
 }: Props & {item: PropSidebarItemCategory}) {
   const {items, label, collapsible, className, href} = item;
@@ -115,7 +102,7 @@ function DocSidebarItemCategory({
 
   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: () => {
@@ -127,6 +114,28 @@ function DocSidebarItemCategory({
   });
 
   useAutoExpandActiveCategory({isActive, collapsed, setCollapsed});
+  const {expandedItem, setExpandedItem} = useDocSidebarItemsExpandedState();
+  function updateCollapsed(toCollapsed: boolean = !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
@@ -152,16 +161,17 @@ function DocSidebarItemCategory({
               ? (e) => {
                   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}
@@ -181,7 +191,7 @@ function DocSidebarItemCategory({
             className="clean-btn menu__caret"
             onClick={(e) => {
               e.preventDefault();
-              toggleCollapsed();
+              updateCollapsed();
             }}
           />
         )}
@@ -205,6 +215,7 @@ function DocSidebarItemLink({
   onItemClick,
   activePath,
   level,
+  index,
   ...props
 }: Props & {item: PropSidebarItemLink}) {
   const {href, label, className} = item;

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

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

package/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,32 @@
+/**
+ * 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, {memo} from 'react';
+import DocSidebarItem from '@theme/DocSidebarItem';
+import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common';
+
+import type {Props} from '@theme/DocSidebarItems';
+
+// TODO this item should probably not receive the "activePath" props
+// TODO this triggers whole sidebar re-renders on navigation
+function DocSidebarItems({items, ...props}: Props): JSX.Element {
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {items.map((item, index) => (
+        <DocSidebarItem
+          key={index} // sidebar is static, the index does not change
+          item={item}
+          index={index}
+          {...props}
+        />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  );
+}
+
+// Optimize sidebar at each "level"
+export default memo(DocSidebarItems);

package/{lib/theme/DocItemFooter → src/theme/DocSidebarItems}/styles.module.css

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.lastUpdated {
-  margin-top: 0.2rem;
-  font-style: italic;
-  font-size: smaller;
-}
-
 @media (min-width: 997px) {
-  .lastUpdated {
-    text-align: right;
+  .menuLinkText {
+    cursor: initial;
+  }
+
+  .menuLinkText:hover {
+    background: none;
+  }
+
+  .menuLinkText.hasHref {
+    cursor: pointer;
   }
 }

package/src/theme/DocVersionBanner/index.tsx

@@ -5,15 +5,15 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {ComponentType} from 'react';
+import React, {type ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import {
   useActivePlugin,
   useDocVersionSuggestions,
-  GlobalVersion,
-} from '@theme/hooks/useDocs';
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
 import {
   ThemeClassNames,
   useDocsPreferredVersion,