@docusaurus/theme-classic 2.4.1 → 3.0.0-beta.0

package/src/theme/{DocPage → DocRoot}/Layout/index.tsx

@@ -7,32 +7,31 @@
 
 import React, {useState} from 'react';
 import {useDocsSidebar} from '@docusaurus/theme-common/internal';
-import Layout from '@theme/Layout';
 import BackToTopButton from '@theme/BackToTopButton';
-import DocPageLayoutSidebar from '@theme/DocPage/Layout/Sidebar';
-import DocPageLayoutMain from '@theme/DocPage/Layout/Main';
-import type {Props} from '@theme/DocPage/Layout';
+import DocRootLayoutSidebar from '@theme/DocRoot/Layout/Sidebar';
+import DocRootLayoutMain from '@theme/DocRoot/Layout/Main';
+import type {Props} from '@theme/DocRoot/Layout';
 
 import styles from './styles.module.css';
 
-export default function DocPageLayout({children}: Props): JSX.Element {
+export default function DocRootLayout({children}: Props): JSX.Element {
   const sidebar = useDocsSidebar();
   const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
   return (
-    <Layout wrapperClassName={styles.docsWrapper}>
+    <div className={styles.docsWrapper}>
       <BackToTopButton />
-      <div className={styles.docPage}>
+      <div className={styles.docRoot}>
         {sidebar && (
-          <DocPageLayoutSidebar
+          <DocRootLayoutSidebar
             sidebar={sidebar.items}
             hiddenSidebarContainer={hiddenSidebarContainer}
             setHiddenSidebarContainer={setHiddenSidebarContainer}
           />
         )}
-        <DocPageLayoutMain hiddenSidebarContainer={hiddenSidebarContainer}>
+        <DocRootLayoutMain hiddenSidebarContainer={hiddenSidebarContainer}>
           {children}
-        </DocPageLayoutMain>
+        </DocRootLayoutMain>
       </div>
-    </Layout>
+    </div>
   );
 }

package/src/theme/{DocPage → DocRoot}/Layout/styles.module.css

@@ -5,10 +5,9 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docPage {
+.docRoot {
   display: flex;
   width: 100%;
-  flex: 1 0;
 }
 
 .docsWrapper {

package/src/theme/DocRoot/index.tsx

@@ -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 {HtmlClassNameProvider, ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  DocsSidebarProvider,
+  useDocRootMetadata,
+} from '@docusaurus/theme-common/internal';
+import DocRootLayout from '@theme/DocRoot/Layout';
+import NotFoundContent from '@theme/NotFound/Content';
+import type {Props} from '@theme/DocRoot';
+
+export default function DocRoot(props: Props): JSX.Element {
+  const currentDocRouteMetadata = useDocRootMetadata(props);
+  if (!currentDocRouteMetadata) {
+    // We only render the not found content to avoid a double layout
+    // see https://github.com/facebook/docusaurus/pull/7966#pullrequestreview-1077276692
+    return <NotFoundContent />;
+  }
+  const {docElement, sidebarName, sidebarItems} = currentDocRouteMetadata;
+  return (
+    <HtmlClassNameProvider className={clsx(ThemeClassNames.page.docsDocPage)}>
+      <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
+        <DocRootLayout>{docElement}</DocRootLayout>
+      </DocsSidebarProvider>
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/DocSidebarItem/Category/index.tsx

@@ -16,7 +16,7 @@ import {
 } from '@docusaurus/theme-common';
 import {
   isActiveSidebarItem,
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   useDocSidebarItemsExpandedState,
   isSamePath,
 } from '@docusaurus/theme-common/internal';
@@ -59,7 +59,7 @@ function useCategoryHrefWithSSRFallback(
 ): string | undefined {
   const isBrowser = useIsBrowser();
   return useMemo(() => {
-    if (item.href) {
+    if (item.href && !item.linkUnlisted) {
       return item.href;
     }
     // In these cases, it's not necessary to render a fallback
@@ -67,28 +67,40 @@ function useCategoryHrefWithSSRFallback(
     if (isBrowser || !item.collapsible) {
       return undefined;
     }
-    return findFirstCategoryLink(item);
+    return findFirstSidebarItemLink(item);
   }, [item, isBrowser]);
 }
 
 function CollapseButton({
+  collapsed,
   categoryLabel,
   onClick,
 }: {
+  collapsed: boolean;
   categoryLabel: string;
   onClick: ComponentProps<'button'>['onClick'];
 }) {
   return (
     <button
-      aria-label={translate(
-        {
-          id: 'theme.DocSidebarItem.toggleCollapsedCategoryAriaLabel',
-          message: "Toggle the collapsible sidebar category '{label}'",
-          description:
-            'The ARIA label to toggle the collapsible sidebar category',
-        },
-        {label: categoryLabel},
-      )}
+      aria-label={
+        collapsed
+          ? translate(
+              {
+                id: 'theme.DocSidebarItem.expandCategoryAriaLabel',
+                message: "Expand sidebar category '{label}'",
+                description: 'The ARIA label to expand the sidebar category',
+              },
+              {label: categoryLabel},
+            )
+          : translate(
+              {
+                id: 'theme.DocSidebarItem.collapseCategoryAriaLabel',
+                message: "Collapse sidebar category '{label}'",
+                description: 'The ARIA label to collapse the sidebar category',
+              },
+              {label: categoryLabel},
+            )
+      }
       type="button"
       className="clean-btn menu__caret"
       onClick={onClick}
@@ -188,6 +200,7 @@ export default function DocSidebarItemCategory({
         </Link>
         {href && collapsible && (
           <CollapseButton
+            collapsed={collapsed}
             categoryLabel={label}
             onClick={(e) => {
               e.preventDefault();

package/src/theme/DocSidebarItems/index.tsx

@@ -6,17 +6,19 @@
  */
 
 import React, {memo} from 'react';
-import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common/internal';
+import {
+  DocSidebarItemsExpandedStateProvider,
+  useVisibleSidebarItems,
+} from '@docusaurus/theme-common/internal';
 import DocSidebarItem from '@theme/DocSidebarItem';
 
 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 {
+  const visibleItems = useVisibleSidebarItems(items, props.activePath);
   return (
     <DocSidebarItemsExpandedStateProvider>
-      {items.map((item, index) => (
+      {visibleItems.map((item, index) => (
         <DocSidebarItem key={index} item={item} index={index} {...props} />
       ))}
     </DocSidebarItemsExpandedStateProvider>

package/src/theme/DocTagDocListPage/index.tsx

@@ -15,9 +15,10 @@ import {
   usePluralForm,
 } from '@docusaurus/theme-common';
 import Translate, {translate} from '@docusaurus/Translate';
-import Layout from '@theme/Layout';
 import SearchMetadata from '@theme/SearchMetadata';
 import type {Props} from '@theme/DocTagDocListPage';
+import Unlisted from '@theme/Unlisted';
+import Heading from '@theme/Heading';
 
 // Very simple pluralization: probably good enough for now
 function useNDocsTaggedPlural() {
@@ -37,59 +38,79 @@ function useNDocsTaggedPlural() {
     );
 }
 
+function usePageTitle(props: Props): string {
+  const nDocsTaggedPlural = useNDocsTaggedPlural();
+  return translate(
+    {
+      id: 'theme.docs.tagDocListPageTitle',
+      description: 'The title of the page for a docs tag',
+      message: '{nDocsTagged} with "{tagName}"',
+    },
+    {nDocsTagged: nDocsTaggedPlural(props.tag.count), tagName: props.tag.label},
+  );
+}
+
 function DocItem({doc}: {doc: Props['tag']['items'][number]}): JSX.Element {
   return (
     <article className="margin-vert--lg">
       <Link to={doc.permalink}>
-        <h2>{doc.title}</h2>
+        <Heading as="h2">{doc.title}</Heading>
       </Link>
       {doc.description && <p>{doc.description}</p>}
     </article>
   );
 }
 
-export default function DocTagDocListPage({tag}: Props): JSX.Element {
-  const nDocsTaggedPlural = useNDocsTaggedPlural();
-  const title = translate(
-    {
-      id: 'theme.docs.tagDocListPageTitle',
-      description: 'The title of the page for a docs tag',
-      message: '{nDocsTagged} with "{tagName}"',
-    },
-    {nDocsTagged: nDocsTaggedPlural(tag.count), tagName: tag.label},
+function DocTagDocListPageMetadata({
+  title,
+}: Props & {title: string}): JSX.Element {
+  return (
+    <>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="doc_tag_doc_list" />
+    </>
   );
+}
 
+function DocTagDocListPageContent({
+  tag,
+  title,
+}: Props & {title: string}): JSX.Element {
   return (
     <HtmlClassNameProvider
-      className={clsx(
-        ThemeClassNames.wrapper.docsPages,
-        ThemeClassNames.page.docsTagDocListPage,
-      )}>
-      <PageMetadata title={title} />
-      <SearchMetadata tag="doc_tag_doc_list" />
-      <Layout>
-        <div className="container margin-vert--lg">
-          <div className="row">
-            <main className="col col--8 col--offset-2">
-              <header className="margin-bottom--xl">
-                <h1>{title}</h1>
-                <Link href={tag.allTagsPath}>
-                  <Translate
-                    id="theme.tags.tagsPageLink"
-                    description="The label of the link targeting the tag list page">
-                    View All Tags
-                  </Translate>
-                </Link>
-              </header>
-              <section className="margin-vert--lg">
-                {tag.items.map((doc) => (
-                  <DocItem key={doc.id} doc={doc} />
-                ))}
-              </section>
-            </main>
-          </div>
+      className={clsx(ThemeClassNames.page.docsTagDocListPage)}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            {tag.unlisted && <Unlisted />}
+            <header className="margin-bottom--xl">
+              <Heading as="h1">{title}</Heading>
+              <Link href={tag.allTagsPath}>
+                <Translate
+                  id="theme.tags.tagsPageLink"
+                  description="The label of the link targeting the tag list page">
+                  View All Tags
+                </Translate>
+              </Link>
+            </header>
+            <section className="margin-vert--lg">
+              {tag.items.map((doc) => (
+                <DocItem key={doc.id} doc={doc} />
+              ))}
+            </section>
+          </main>
         </div>
-      </Layout>
+      </div>
     </HtmlClassNameProvider>
   );
 }
+
+export default function DocTagDocListPage(props: Props): JSX.Element {
+  const title = usePageTitle(props);
+  return (
+    <>
+      <DocTagDocListPageMetadata {...props} title={title} />
+      <DocTagDocListPageContent {...props} title={title} />
+    </>
+  );
+}

package/src/theme/DocTagsListPage/index.tsx

@@ -13,31 +13,47 @@ import {
   ThemeClassNames,
   translateTagsPageTitle,
 } from '@docusaurus/theme-common';
-import Layout from '@theme/Layout';
 import TagsListByLetter from '@theme/TagsListByLetter';
 import SearchMetadata from '@theme/SearchMetadata';
 import type {Props} from '@theme/DocTagsListPage';
+import Heading from '@theme/Heading';
 
-export default function DocTagsListPage({tags}: Props): JSX.Element {
-  const title = translateTagsPageTitle();
+function DocTagsListPageMetadata({
+  title,
+}: Props & {title: string}): JSX.Element {
   return (
-    <HtmlClassNameProvider
-      className={clsx(
-        ThemeClassNames.wrapper.docsPages,
-        ThemeClassNames.page.docsTagsListPage,
-      )}>
+    <>
       <PageMetadata title={title} />
       <SearchMetadata tag="doc_tags_list" />
-      <Layout>
-        <div className="container margin-vert--lg">
-          <div className="row">
-            <main className="col col--8 col--offset-2">
-              <h1>{title}</h1>
-              <TagsListByLetter tags={tags} />
-            </main>
-          </div>
+    </>
+  );
+}
+
+function DocTagsListPageContent({
+  tags,
+  title,
+}: Props & {title: string}): JSX.Element {
+  return (
+    <HtmlClassNameProvider
+      className={clsx(ThemeClassNames.page.docsTagsListPage)}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            <Heading as="h1">{title}</Heading>
+            <TagsListByLetter tags={tags} />
+          </main>
         </div>
-      </Layout>
+      </div>
     </HtmlClassNameProvider>
   );
 }
+
+export default function DocTagsListPage(props: Props): JSX.Element {
+  const title = translateTagsPageTitle();
+  return (
+    <>
+      <DocTagsListPageMetadata {...props} title={title} />
+      <DocTagsListPageContent {...props} title={title} />
+    </>
+  );
+}

package/src/theme/DocVersionRoot/index.tsx

@@ -0,0 +1,51 @@
+/**
+ * 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 {HtmlClassNameProvider, PageMetadata} from '@docusaurus/theme-common';
+import {
+  docVersionSearchTag,
+  DocsVersionProvider,
+} from '@docusaurus/theme-common/internal';
+import renderRoutes from '@docusaurus/renderRoutes';
+import SearchMetadata from '@theme/SearchMetadata';
+
+import type {Props} from '@theme/DocVersionRoot';
+
+function DocVersionRootMetadata(props: Props): JSX.Element {
+  const {version} = props;
+  return (
+    <>
+      <SearchMetadata
+        version={version.version}
+        tag={docVersionSearchTag(version.pluginId, version.version)}
+      />
+      <PageMetadata>
+        {version.noIndex && <meta name="robots" content="noindex, nofollow" />}
+      </PageMetadata>
+    </>
+  );
+}
+
+function DocVersionRootContent(props: Props): JSX.Element {
+  const {version, route} = props;
+  return (
+    <HtmlClassNameProvider className={version.className}>
+      <DocsVersionProvider version={version}>
+        {renderRoutes(route.routes!)}
+      </DocsVersionProvider>
+    </HtmlClassNameProvider>
+  );
+}
+export default function DocVersionRoot(props: Props): JSX.Element {
+  return (
+    <>
+      <DocVersionRootMetadata {...props} />
+      <DocVersionRootContent {...props} />
+    </>
+  );
+}

package/src/theme/DocsRoot/index.tsx

@@ -0,0 +1,22 @@
+/**
+ * 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 {ThemeClassNames, HtmlClassNameProvider} from '@docusaurus/theme-common';
+import renderRoutes from '@docusaurus/renderRoutes';
+import Layout from '@theme/Layout';
+
+import type {Props} from '@theme/DocVersionRoot';
+
+export default function DocsRoot(props: Props): JSX.Element {
+  return (
+    <HtmlClassNameProvider className={clsx(ThemeClassNames.wrapper.docsPages)}>
+      <Layout>{renderRoutes(props.route.routes!)}</Layout>
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/EditThisPage/index.tsx

@@ -8,22 +8,19 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import {ThemeClassNames} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
 import IconEdit from '@theme/Icon/Edit';
 import type {Props} from '@theme/EditThisPage';
 
 export default function EditThisPage({editUrl}: Props): JSX.Element {
   return (
-    <a
-      href={editUrl}
-      target="_blank"
-      rel="noreferrer noopener"
-      className={ThemeClassNames.common.editThisPage}>
+    <Link to={editUrl} className={ThemeClassNames.common.editThisPage}>
       <IconEdit />
       <Translate
         id="theme.common.editThisPage"
         description="The link label to edit the current page">
         Edit this page
       </Translate>
-    </a>
+    </Link>
   );
 }

package/src/theme/ErrorPageContent.tsx

@@ -12,6 +12,7 @@ import {
   ErrorBoundaryTryAgainButton,
 } from '@docusaurus/theme-common';
 import type {Props} from '@theme/Error';
+import Heading from '@theme/Heading';
 
 export default function ErrorPageContent({
   error,
@@ -21,13 +22,13 @@ export default function ErrorPageContent({
     <main className="container margin-vert--xl">
       <div className="row">
         <div className="col col--6 col--offset-3">
-          <h1 className="hero__title">
+          <Heading as="h1" className="hero__title">
             <Translate
               id="theme.ErrorPageContent.title"
               description="The title of the fallback page when the page crashed">
               This page crashed.
             </Translate>
-          </h1>
+          </Heading>
           <div className="margin-vert--lg">
             <ErrorBoundaryTryAgainButton
               onClick={tryAgain}

package/src/theme/MDXComponents/Code.tsx

@@ -6,50 +6,13 @@
  */
 
 import type {ComponentProps} from 'react';
-import React, {isValidElement} from 'react';
+import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
 import type {Props} from '@theme/MDXComponents/Code';
 
 export default function MDXCode(props: Props): JSX.Element {
-  const inlineElements: (string | undefined)[] = [
-    'a',
-    'abbr',
-    'b',
-    'br',
-    'button',
-    'cite',
-    'code',
-    'del',
-    'dfn',
-    'em',
-    'i',
-    'img',
-    'input',
-    'ins',
-    'kbd',
-    'label',
-    'object',
-    'output',
-    'q',
-    'ruby',
-    's',
-    'small',
-    'span',
-    'strong',
-    'sub',
-    'sup',
-    'time',
-    'u',
-    'var',
-    'wbr',
-  ];
   const shouldBeInline = React.Children.toArray(props.children).every(
-    (el) =>
-      (typeof el === 'string' && !el.includes('\n')) ||
-      (isValidElement(el) &&
-        inlineElements.includes(
-          (el.props as {mdxType: string} | null)?.mdxType,
-        )),
+    (el) => typeof el === 'string' && !el.includes('\n'),
   );
 
   return shouldBeInline ? (

package/src/theme/MDXComponents/Details.tsx

@@ -15,8 +15,7 @@ export default function MDXDetails(props: Props): JSX.Element {
   // Details theme component
   const summary = items.find(
     (item): item is ReactElement<ComponentProps<'summary'>> =>
-      React.isValidElement(item) &&
-      (item.props as {mdxType: string} | null)?.mdxType === 'summary',
+      React.isValidElement(item) && item.type === 'summary',
   );
   const children = <>{items.filter((item) => item !== summary)}</>;
 

package/src/theme/MDXComponents/Pre.tsx

@@ -5,19 +5,11 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React, {isValidElement} from 'react';
-import CodeBlock from '@theme/CodeBlock';
+import React, {type ReactNode} from 'react';
 import type {Props} from '@theme/MDXComponents/Pre';
 
-export default function MDXPre(props: Props): JSX.Element {
-  return (
-    <CodeBlock
-      // If this pre is created by a ``` fenced codeblock, unwrap the children
-      {...(isValidElement(props.children) &&
-      (props.children.props as {originalType: string} | null)?.originalType ===
-        'code'
-        ? props.children.props
-        : {...props})}
-    />
-  );
+export default function MDXPre(props: Props): ReactNode | undefined {
+  // With MDX 2, this element is only used for fenced code blocks
+  // It always receives a MDXComponents/Code as children
+  return <>{props.children}</>;
 }

package/src/theme/MDXComponents/Ul/index.tsx

@@ -11,7 +11,11 @@ import type {Props} from '@theme/MDXComponents/Ul';
 
 import styles from './styles.module.css';
 
-function transformUlClassName(className?: string): string {
+function transformUlClassName(className?: string): string | undefined {
+  // Fix https://github.com/facebook/docusaurus/issues/9098
+  if (typeof className === 'undefined') {
+    return undefined;
+  }
   return clsx(
     className,
     // This class is set globally by GitHub/MDX. We keep the global class, and

package/src/theme/MDXComponents/index.tsx

@@ -5,8 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
-import MDXHead from '@theme/MDXComponents/Head';
+import React, {type ComponentProps} from 'react';
+import Head from '@docusaurus/Head';
 import MDXCode from '@theme/MDXComponents/Code';
 import MDXA from '@theme/MDXComponents/A';
 import MDXPre from '@theme/MDXComponents/Pre';
@@ -20,19 +20,20 @@ import Mermaid from '@theme/Mermaid';
 import type {MDXComponentsObject} from '@theme/MDXComponents';
 
 const MDXComponents: MDXComponentsObject = {
-  head: MDXHead,
+  Head,
+  details: MDXDetails, // For MD mode support, see https://github.com/facebook/docusaurus/issues/9092#issuecomment-1602902274
+  Details: MDXDetails,
   code: MDXCode,
   a: MDXA,
   pre: MDXPre,
-  details: MDXDetails,
   ul: MDXUl,
   img: MDXImg,
-  h1: (props) => <MDXHeading as="h1" {...props} />,
-  h2: (props) => <MDXHeading as="h2" {...props} />,
-  h3: (props) => <MDXHeading as="h3" {...props} />,
-  h4: (props) => <MDXHeading as="h4" {...props} />,
-  h5: (props) => <MDXHeading as="h5" {...props} />,
-  h6: (props) => <MDXHeading as="h6" {...props} />,
+  h1: (props: ComponentProps<'h1'>) => <MDXHeading as="h1" {...props} />,
+  h2: (props: ComponentProps<'h2'>) => <MDXHeading as="h2" {...props} />,
+  h3: (props: ComponentProps<'h3'>) => <MDXHeading as="h3" {...props} />,
+  h4: (props: ComponentProps<'h4'>) => <MDXHeading as="h4" {...props} />,
+  h5: (props: ComponentProps<'h5'>) => <MDXHeading as="h5" {...props} />,
+  h6: (props: ComponentProps<'h6'>) => <MDXHeading as="h6" {...props} />,
   admonition: Admonition,
   mermaid: Mermaid,
 };