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

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

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+
+.wordWrapButtonIcon {
+  width: 1.2rem;
+  height: 1.2rem;
+}
+
+.wordWrapButtonEnabled .wordWrapButtonIcon {
+  color: var(--ifm-color-primary);
+}

package/src/theme/CodeBlock/index.tsx

@@ -5,145 +5,41 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {isValidElement, useEffect, useState} from 'react';
-import clsx from 'clsx';
-import Highlight, {defaultProps, type Language} from 'prism-react-renderer';
-import {
-  useThemeConfig,
-  parseCodeBlockTitle,
-  parseLanguage,
-  parseLines,
-  ThemeClassNames,
-  usePrismTheme,
-} from '@docusaurus/theme-common';
-import CopyButton from '@theme/CodeBlock/CopyButton';
+import React, {isValidElement, type ReactNode} from 'react';
+import useIsBrowser from '@docusaurus/useIsBrowser';
 import type {Props} from '@theme/CodeBlock';
+import ElementContent from '@theme/CodeBlock/Content/Element';
+import StringContent from '@theme/CodeBlock/Content/String';
 
-import styles from './styles.module.css';
-
-export default function CodeBlock({
-  children,
-  className: blockClassName = '',
-  metastring,
-  title,
-  language: languageProp,
-}: Props): JSX.Element {
-  const {prism} = useThemeConfig();
-
-  const [mounted, setMounted] = useState(false);
-  // The Prism theme on SSR is always the default theme but the site theme
-  // can be in a different mode. React hydration doesn't update DOM styles
-  // that come from SSR. Hence force a re-render after mounting to apply the
-  // current relevant styles. There will be a flash seen of the original
-  // styles seen using this current approach but that's probably ok. Fixing
-  // the flash will require changing the theming approach and is not worth it
-  // at this point.
-  useEffect(() => {
-    setMounted(true);
-  }, []);
-
-  // 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();
-
-  // <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.
+/**
+ * Best attempt to make the children a plain string so it is copyable. If there
+ * are react elements, we will not be able to copy the content, and it will
+ * return `children` as-is; otherwise, it concatenates the string children
+ * together.
+ */
+function maybeStringifyChildren(children: ReactNode): ReactNode {
   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>
-    );
+    return children;
   }
-
   // The children is now guaranteed to be one/more plain strings
-  const content = Array.isArray(children)
-    ? children.join('')
-    : (children as string);
-
-  const language =
-    languageProp ?? parseLanguage(blockClassName) ?? prism.defaultLanguage;
-  const {highlightLines, code} = parseLines(content, metastring, language);
+  return Array.isArray(children) ? children.join('') : (children as string);
+}
 
+export default function CodeBlock({
+  children: rawChildren,
+  ...props
+}: Props): JSX.Element {
+  // The Prism theme on SSR is always the default theme but the site theme can
+  // be in a different mode. React hydration doesn't update DOM styles that come
+  // from SSR. Hence force a re-render after mounting to apply the current
+  // relevant styles.
+  const isBrowser = useIsBrowser();
+  const children = maybeStringifyChildren(rawChildren);
+  const CodeBlockComp =
+    typeof children === 'string' ? StringContent : ElementContent;
   return (
-    <Highlight
-      {...defaultProps}
-      key={String(mounted)}
-      theme={prismTheme}
-      code={code}
-      language={(language ?? 'text') as Language}>
-      {({className, style, tokens, getLineProps, getTokenProps}) => (
-        <div
-          className={clsx(
-            styles.codeBlockContainer,
-            blockClassName,
-            {
-              [`language-${language}`]:
-                language && !blockClassName.includes(`language-${language}`),
-            },
-            ThemeClassNames.common.codeBlock,
-          )}>
-          {codeBlockTitle && (
-            <div style={style} className={styles.codeBlockTitle}>
-              {codeBlockTitle}
-            </div>
-          )}
-          <div className={styles.codeBlockContent} style={style}>
-            <pre
-              /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
-              tabIndex={0}
-              className={clsx(className, styles.codeBlock, 'thin-scrollbar')}>
-              <code className={styles.codeBlockLines}>
-                {tokens.map((line, i) => {
-                  if (line.length === 1 && line[0]!.content === '\n') {
-                    line[0]!.content = '';
-                  }
-
-                  const lineProps = getLineProps({line, key: i});
-
-                  if (highlightLines.includes(i)) {
-                    lineProps.className += ' docusaurus-highlight-code-line';
-                  }
-
-                  return (
-                    <span key={i} {...lineProps}>
-                      {line.map((token, key) => (
-                        <span key={key} {...getTokenProps({token, key})} />
-                      ))}
-                      <br />
-                    </span>
-                  );
-                })}
-              </code>
-            </pre>
-
-            <CopyButton code={code} />
-          </div>
-        </div>
-      )}
-    </Highlight>
+    <CodeBlockComp key={String(isBrowser)} {...props}>
+      {children as string}
+    </CodeBlockComp>
   );
 }

package/src/theme/Details/index.tsx

@@ -7,7 +7,7 @@
 
 import React from 'react';
 import clsx from 'clsx';
-import {Details as DetailsGeneric} from '@docusaurus/theme-common';
+import {Details as DetailsGeneric} from '@docusaurus/theme-common/Details';
 import type {Props} from '@theme/Details';
 import styles from './styles.module.css';
 

package/src/theme/DocBreadcrumbs/index.tsx

@@ -15,24 +15,38 @@ import styles from './styles.module.css';
 import clsx from 'clsx';
 import Link from '@docusaurus/Link';
 import useBaseUrl from '@docusaurus/useBaseUrl';
+import {translate} from '@docusaurus/Translate';
+import IconHome from '@theme/IconHome';
 
 // TODO move to design system folder
 function BreadcrumbsItemLink({
   children,
   href,
+  isLast,
 }: {
   children: ReactNode;
-  href?: string;
+  href: string | undefined;
+  isLast: boolean;
 }): JSX.Element {
   const className = 'breadcrumbs__link';
+  if (isLast) {
+    return (
+      <span className={className} itemProp="name">
+        {children}
+      </span>
+    );
+  }
   return href ? (
     <Link className={className} href={href} itemProp="item">
       <span itemProp="name">{children}</span>
     </Link>
   ) : (
-    <span className={className} itemProp="item name">
-      {children}
-    </span>
+    // TODO Google search console doesn't like breadcrumb items without href.
+    // The schema doesn't seem to require `id` for each `item`, although Google
+    // insist to infer one, even if it's invalid. Removing `itemProp="item
+    // name"` for now, since I don't know how to properly fix it.
+    // See https://github.com/facebook/docusaurus/issues/7241
+    <span className={className}>{children}</span>
   );
 }
 
@@ -41,16 +55,20 @@ function BreadcrumbsItem({
   children,
   active,
   index,
+  addMicrodata,
 }: {
   children: ReactNode;
   active?: boolean;
   index: number;
+  addMicrodata: boolean;
 }): JSX.Element {
   return (
     <li
-      itemScope
-      itemProp="itemListElement"
-      itemType="https://schema.org/ListItem"
+      {...(addMicrodata && {
+        itemScope: true,
+        itemProp: 'itemListElement',
+        itemType: 'https://schema.org/ListItem',
+      })}
       className={clsx('breadcrumbs__item', {
         'breadcrumbs__item--active': active,
       })}>
@@ -65,9 +83,14 @@ function HomeBreadcrumbItem() {
   return (
     <li className="breadcrumbs__item">
       <Link
+        aria-label={translate({
+          id: 'theme.docs.breadcrumbs.home',
+          message: 'Home page',
+          description: 'The ARIA label for the home page in the breadcrumbs',
+        })}
         className={clsx('breadcrumbs__link', styles.breadcrumbsItemLink)}
         href={homeHref}>
-        🏠
+        <IconHome className={styles.breadcrumbHomeIcon} />
       </Link>
     </li>
   );
@@ -87,23 +110,30 @@ export default function DocBreadcrumbs(): JSX.Element | null {
         ThemeClassNames.docs.docBreadcrumbs,
         styles.breadcrumbsContainer,
       )}
-      aria-label="breadcrumbs">
+      aria-label={translate({
+        id: 'theme.docs.breadcrumbs.navAriaLabel',
+        message: 'Breadcrumbs',
+        description: 'The ARIA label for the breadcrumbs',
+      })}>
       <ul
         className="breadcrumbs"
         itemScope
         itemType="https://schema.org/BreadcrumbList">
         {homePageRoute && <HomeBreadcrumbItem />}
-        {breadcrumbs.map((item, idx) => (
-          <BreadcrumbsItem
-            key={idx}
-            active={idx === breadcrumbs.length - 1}
-            index={idx}>
-            <BreadcrumbsItemLink
-              href={idx < breadcrumbs.length - 1 ? item.href : undefined}>
-              {item.label}
-            </BreadcrumbsItemLink>
-          </BreadcrumbsItem>
-        ))}
+        {breadcrumbs.map((item, idx) => {
+          const isLast = idx === breadcrumbs.length - 1;
+          return (
+            <BreadcrumbsItem
+              key={idx}
+              active={isLast}
+              index={idx}
+              addMicrodata={!!item.href}>
+              <BreadcrumbsItemLink href={item.href} isLast={isLast}>
+                {item.label}
+              </BreadcrumbsItemLink>
+            </BreadcrumbsItem>
+          );
+        })}
       </ul>
     </nav>
   );

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

@@ -9,3 +9,11 @@
   --ifm-breadcrumb-size-multiplier: 0.8;
   margin-bottom: 0.8rem;
 }
+
+.breadcrumbHomeIcon {
+  position: relative;
+  top: 1px;
+  vertical-align: top;
+  height: 1.1rem;
+  width: 1.1rem;
+}

package/src/theme/DocCardList/index.tsx

@@ -6,10 +6,12 @@
  */
 
 import React from 'react';
+import clsx from 'clsx';
 
 import DocCard from '@theme/DocCard';
 import type {PropSidebarItem} from '@docusaurus/plugin-content-docs';
 import {findFirstCategoryLink} from '@docusaurus/theme-common';
+import type {Props} from '@theme/DocCardList';
 
 // Filter categories that don't have a link.
 function filterItems(items: PropSidebarItem[]): PropSidebarItem[] {
@@ -21,18 +23,14 @@ function filterItems(items: PropSidebarItem[]): PropSidebarItem[] {
   });
 }
 
-export default function DocCardList({
-  items,
-}: {
-  items: PropSidebarItem[];
-}): JSX.Element {
+export default function DocCardList({items, className}: Props): JSX.Element {
   return (
-    <div className="row">
+    <section className={clsx('row', className)}>
       {filterItems(items).map((item, index) => (
         <article key={index} className="col col--6 margin-bottom--lg">
           <DocCard key={index} item={item} />
         </article>
       ))}
-    </div>
+    </section>
   );
 }

package/src/theme/DocCategoryGeneratedIndexPage/index.tsx

@@ -60,9 +60,9 @@ function DocCategoryGeneratedIndexPageContent({
             <p>{categoryGeneratedIndex.description}</p>
           )}
         </header>
-        <main className="margin-top--lg">
-          <DocCardList items={category.items} />
-        </main>
+        <article className="margin-top--lg">
+          <DocCardList items={category.items} className={styles.list} />
+        </article>
         <footer className="margin-top--lg">
           <DocPaginator
             previous={categoryGeneratedIndex.navigation.previous}

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

@@ -9,6 +9,10 @@
   .generatedIndexPage {
     max-width: 75% !important;
   }
+
+  .list article:nth-last-child(-n + 2) {
+    margin-bottom: 0 !important;
+  }
 }
 
 /* Duplicated from .markdown h1 */
@@ -16,3 +20,7 @@
   --ifm-h1-font-size: 3rem;
   margin-bottom: calc(1.25 * var(--ifm-leading));
 }
+
+.list article:last-child {
+  margin-bottom: 0 !important;
+}

package/src/theme/DocItem/index.tsx

@@ -47,7 +47,7 @@ function DocItemContent(props: Props): JSX.Element {
   const {title} = metadata;
 
   // We only add a title if:
-  // - user asks to hide it with front matter
+  // - user doesn't ask 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';

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

@@ -20,3 +20,9 @@
     display: none;
   }
 }
+
+@media print {
+  .tocMobile {
+    display: none;
+  }
+}

package/src/theme/DocPage/Layout/Main/index.tsx

@@ -0,0 +1,37 @@
+/**
+ * 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 {useDocsSidebar} from '@docusaurus/theme-common';
+
+import clsx from 'clsx';
+import styles from './styles.module.css';
+import type {Props} from '@theme/DocPage/Layout/Main';
+
+export default function DocPageLayoutMain({
+  hiddenSidebarContainer,
+  children,
+}: Props): JSX.Element {
+  const sidebar = useDocsSidebar();
+  return (
+    <main
+      className={clsx(
+        styles.docMainContainer,
+        (hiddenSidebarContainer || !sidebar) && styles.docMainContainerEnhanced,
+      )}>
+      <div
+        className={clsx(
+          'container padding-top--md padding-bottom--lg',
+          styles.docItemWrapper,
+          hiddenSidebarContainer && styles.docItemWrapperEnhanced,
+        )}>
+        {children}
+      </div>
+    </main>
+  );
+}

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

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+
+.docMainContainer {
+  display: flex;
+  width: 100%;
+}
+
+@media (min-width: 997px) {
+  .docMainContainer {
+    flex-grow: 1;
+    max-width: calc(100% - var(--doc-sidebar-width));
+  }
+
+  .docMainContainerEnhanced {
+    max-width: calc(100% - var(--doc-sidebar-hidden-width));
+  }
+
+  .docItemWrapperEnhanced {
+    max-width: calc(
+      var(--ifm-container-width) + var(--doc-sidebar-width)
+    ) !important;
+  }
+}

package/src/theme/DocPage/Layout/Sidebar/ExpandButton/index.tsx

@@ -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 IconArrow from '@theme/IconArrow';
+import {translate} from '@docusaurus/Translate';
+import type {Props} from '@theme/DocPage/Layout/Sidebar/ExpandButton';
+
+import styles from './styles.module.css';
+
+export default function DocPageLayoutSidebarExpandButton({
+  toggleSidebar,
+}: Props): JSX.Element {
+  return (
+    <div
+      className={styles.expandButton}
+      title={translate({
+        id: 'theme.docs.sidebar.expandButtonTitle',
+        message: 'Expand sidebar',
+        description:
+          'The ARIA label and title attribute for expand button of doc sidebar',
+      })}
+      aria-label={translate({
+        id: 'theme.docs.sidebar.expandButtonAriaLabel',
+        message: 'Expand sidebar',
+        description:
+          'The ARIA label and title attribute for expand button of doc sidebar',
+      })}
+      tabIndex={0}
+      role="button"
+      onKeyDown={toggleSidebar}
+      onClick={toggleSidebar}>
+      <IconArrow className={styles.expandButtonIcon} />
+    </div>
+  );
+}

package/src/theme/DocPage/Layout/Sidebar/ExpandButton/styles.module.css

@@ -0,0 +1,33 @@
+/**
+ * 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.
+ */
+
+@media (min-width: 997px) {
+  .expandButton {
+    position: sticky;
+    top: 0;
+    height: 100%;
+    max-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    transition: background-color var(--ifm-transition-fast) ease;
+    background-color: var(--docusaurus-collapse-button-bg);
+  }
+
+  .expandButton:hover,
+  .expandButton:focus {
+    background-color: var(--docusaurus-collapse-button-bg-hover);
+  }
+
+  .expandButtonIcon {
+    transform: rotate(0);
+  }
+
+  [dir='rtl'] .expandButtonIcon {
+    transform: rotate(180deg);
+  }
+}

package/src/theme/DocPage/Layout/Sidebar/index.module.css

@@ -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.
+ */
+
+:root {
+  --doc-sidebar-width: 300px;
+  --doc-sidebar-hidden-width: 30px;
+}
+
+.docSidebarContainer {
+  display: none;
+}
+
+@media (min-width: 997px) {
+  .docSidebarContainer {
+    display: block;
+    width: var(--doc-sidebar-width);
+    margin-top: calc(-1 * var(--ifm-navbar-height));
+    border-right: 1px solid var(--ifm-toc-border-color);
+    will-change: width;
+    transition: width var(--ifm-transition-fast) ease;
+    clip-path: inset(0);
+  }
+
+  .docSidebarContainerHidden {
+    width: var(--doc-sidebar-hidden-width);
+    cursor: pointer;
+  }
+}

package/src/theme/DocPage/Layout/Sidebar/index.tsx

@@ -0,0 +1,74 @@
+/**
+ * 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, useState, useCallback} from 'react';
+import DocSidebar from '@theme/DocSidebar';
+import {useLocation} from '@docusaurus/router';
+import type {Props} from '@theme/DocPage/Layout/Sidebar';
+import ExpandButton from '@theme/DocPage/Layout/Sidebar/ExpandButton';
+
+import clsx from 'clsx';
+import styles from './index.module.css';
+
+import {ThemeClassNames, useDocsSidebar} from '@docusaurus/theme-common';
+
+// Reset sidebar state when sidebar changes
+// Use React key to unmount/remount the children
+// See https://github.com/facebook/docusaurus/issues/3414
+function ResetOnSidebarChange({children}: {children: ReactNode}) {
+  const sidebar = useDocsSidebar();
+  return (
+    <React.Fragment key={sidebar?.name ?? 'noSidebar'}>
+      {children}
+    </React.Fragment>
+  );
+}
+
+export default function DocPageLayoutSidebar({
+  sidebar,
+  hiddenSidebarContainer,
+  setHiddenSidebarContainer,
+}: Props): JSX.Element {
+  const {pathname} = useLocation();
+
+  const [hiddenSidebar, setHiddenSidebar] = useState(false);
+  const toggleSidebar = useCallback(() => {
+    if (hiddenSidebar) {
+      setHiddenSidebar(false);
+    }
+    setHiddenSidebarContainer((value) => !value);
+  }, [setHiddenSidebarContainer, hiddenSidebar]);
+
+  return (
+    <aside
+      className={clsx(
+        ThemeClassNames.docs.docSidebarContainer,
+        styles.docSidebarContainer,
+        hiddenSidebarContainer && styles.docSidebarContainerHidden,
+      )}
+      onTransitionEnd={(e) => {
+        if (!e.currentTarget.classList.contains(styles.docSidebarContainer!)) {
+          return;
+        }
+
+        if (hiddenSidebarContainer) {
+          setHiddenSidebar(true);
+        }
+      }}>
+      <ResetOnSidebarChange>
+        <DocSidebar
+          sidebar={sidebar}
+          path={pathname}
+          onCollapse={toggleSidebar}
+          isHidden={hiddenSidebar}
+        />
+      </ResetOnSidebarChange>
+
+      {hiddenSidebar && <ExpandButton toggleSidebar={toggleSidebar} />}
+    </aside>
+  );
+}