@docusaurus/theme-classic 2.4.0 → 3.0.0-alpha.0

package/lib/theme/DocRoot/index.js

@@ -0,0 +1,31 @@
+/**
+ * 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';
+export default function DocRoot(props) {
+  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/lib/theme/DocSidebarItem/Category/index.js

@@ -15,7 +15,7 @@ import {
 } from '@docusaurus/theme-common';
 import {
   isActiveSidebarItem,
-  findFirstCategoryLink,
+  findFirstSidebarItemLink,
   useDocSidebarItemsExpandedState,
   isSamePath,
 } from '@docusaurus/theme-common/internal';
@@ -45,7 +45,7 @@ function useAutoExpandActiveCategory({isActive, collapsed, updateCollapsed}) {
 function useCategoryHrefWithSSRFallback(item) {
   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
@@ -53,7 +53,7 @@ function useCategoryHrefWithSSRFallback(item) {
     if (isBrowser || !item.collapsible) {
       return undefined;
     }
-    return findFirstCategoryLink(item);
+    return findFirstSidebarItemLink(item);
   }, [item, isBrowser]);
 }
 function CollapseButton({categoryLabel, onClick}) {

package/lib/theme/DocSidebarItems/index.js

@@ -5,14 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 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';
-// TODO this item should probably not receive the "activePath" props
-// TODO this triggers whole sidebar re-renders on navigation
 function DocSidebarItems({items, ...props}) {
+  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/lib/theme/DocTagDocListPage/index.d.ts

@@ -7,4 +7,4 @@
 /// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="react" />
 import type { Props } from '@theme/DocTagDocListPage';
-export default function DocTagDocListPage({ tag }: Props): JSX.Element;
+export default function DocTagDocListPage(props: Props): JSX.Element;

package/lib/theme/DocTagDocListPage/index.js

@@ -14,8 +14,9 @@ import {
   usePluralForm,
 } from '@docusaurus/theme-common';
 import Translate, {translate} from '@docusaurus/Translate';
-import Layout from '@theme/Layout';
 import SearchMetadata from '@theme/SearchMetadata';
+import Unlisted from '@theme/Unlisted';
+import Heading from '@theme/Heading';
 // Very simple pluralization: probably good enough for now
 function useNDocsTaggedPlural() {
   const {selectMessage} = usePluralForm();
@@ -33,57 +34,70 @@ function useNDocsTaggedPlural() {
       ),
     );
 }
+function usePageTitle(props) {
+  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}) {
   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}) {
-  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}) {
   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>
+    </>
+  );
+}
+function DocTagDocListPageContent({tag, title}) {
+  return (
+    <HtmlClassNameProvider
+      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) {
+  const title = usePageTitle(props);
+  return (
+    <>
+      <DocTagDocListPageMetadata {...props} title={title} />
+      <DocTagDocListPageContent {...props} title={title} />
+    </>
+  );
+}

package/lib/theme/DocTagsListPage/index.d.ts

@@ -7,4 +7,4 @@
 /// <reference types="@docusaurus/plugin-content-docs" />
 /// <reference types="react" />
 import type { Props } from '@theme/DocTagsListPage';
-export default function DocTagsListPage({ tags }: Props): JSX.Element;
+export default function DocTagsListPage(props: Props): JSX.Element;

package/lib/theme/DocTagsListPage/index.js

@@ -12,29 +12,38 @@ import {
   ThemeClassNames,
   translateTagsPageTitle,
 } from '@docusaurus/theme-common';
-import Layout from '@theme/Layout';
 import TagsListByLetter from '@theme/TagsListByLetter';
 import SearchMetadata from '@theme/SearchMetadata';
-export default function DocTagsListPage({tags}) {
-  const title = translateTagsPageTitle();
+import Heading from '@theme/Heading';
+function DocTagsListPageMetadata({title}) {
   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}) {
+  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) {
+  const title = translateTagsPageTitle();
+  return (
+    <>
+      <DocTagsListPageMetadata {...props} title={title} />
+      <DocTagsListPageContent {...props} title={title} />
+    </>
+  );
+}

package/lib/theme/DocVersionRoot/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/// <reference types="@docusaurus/plugin-content-docs" />
+/// <reference types="react" />
+import type { Props } from '@theme/DocVersionRoot';
+export default function DocVersionRoot(props: Props): JSX.Element;

package/lib/theme/DocVersionRoot/index.js

@@ -0,0 +1,46 @@
+/**
+ * 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';
+function DocVersionRootMetadata(props) {
+  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) {
+  const {version, route} = props;
+  return (
+    <HtmlClassNameProvider className={version.className}>
+      <DocsVersionProvider version={version}>
+        {renderRoutes(route.routes)}
+      </DocsVersionProvider>
+    </HtmlClassNameProvider>
+  );
+}
+export default function DocVersionRoot(props) {
+  return (
+    <>
+      <DocVersionRootMetadata {...props} />
+      <DocVersionRootContent {...props} />
+    </>
+  );
+}

package/lib/theme/DocsRoot/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ */
+/// <reference types="@docusaurus/plugin-content-docs" />
+/// <reference types="react" />
+import type { Props } from '@theme/DocVersionRoot';
+export default function DocsRoot(props: Props): JSX.Element;

package/lib/theme/DocsRoot/index.js

@@ -0,0 +1,18 @@
+/**
+ * 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';
+export default function DocsRoot(props) {
+  return (
+    <HtmlClassNameProvider className={clsx(ThemeClassNames.wrapper.docsPages)}>
+      <Layout>{renderRoutes(props.route.routes)}</Layout>
+    </HtmlClassNameProvider>
+  );
+}

package/lib/theme/EditThisPage/index.js

@@ -7,20 +7,17 @@
 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';
 export default function EditThisPage({editUrl}) {
   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/lib/theme/ErrorPageContent.js

@@ -10,18 +10,19 @@ import {
   ErrorBoundaryError,
   ErrorBoundaryTryAgainButton,
 } from '@docusaurus/theme-common';
+import Heading from '@theme/Heading';
 export default function ErrorPageContent({error, tryAgain}) {
   return (
     <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/lib/theme/{MDXComponents/Head.d.ts → Icon/Copy/index.d.ts}

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/MDXComponents/Head';
-export default function MDXHead(props: Props): JSX.Element;
+import type { Props } from '@theme/Icon/Copy';
+export default function IconCopy(props: Props): JSX.Element;

package/lib/theme/Icon/Copy/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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';
+export default function IconCopy(props) {
+  return (
+    <svg viewBox="0 0 24 24" {...props}>
+      <path
+        fill="currentColor"
+        d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"
+      />
+    </svg>
+  );
+}

package/lib/theme/Icon/Success/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/Icon/Success';
+export default function IconSuccess(props: Props): JSX.Element;

package/lib/theme/Icon/Success/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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';
+export default function IconSuccess(props) {
+  return (
+    <svg viewBox="0 0 24 24" {...props}>
+      <path
+        fill="currentColor"
+        d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"
+      />
+    </svg>
+  );
+}

package/lib/theme/Icon/WordWrap/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/Icon/WordWrap';
+export default function IconWordWrap(props: Props): JSX.Element;

package/lib/theme/Icon/WordWrap/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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';
+export default function IconWordWrap(props) {
+  return (
+    <svg viewBox="0 0 24 24" {...props}>
+      <path
+        fill="currentColor"
+        d="M4 19h6v-2H4v2zM20 5H4v2h16V5zm-3 6H4v2h13.25c1.1 0 2 .9 2 2s-.9 2-2 2H15v-2l-3 3l3 3v-2h2c2.21 0 4-1.79 4-4s-1.79-4-4-4z"
+      />
+    </svg>
+  );
+}

package/lib/theme/MDXComponents/Code.js

@@ -4,45 +4,11 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {isValidElement} from 'react';
+import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
 export default function MDXCode(props) {
-  const inlineElements = [
-    '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?.mdxType)),
+    (el) => typeof el === 'string' && !el.includes('\n'),
   );
   return shouldBeInline ? <code {...props} /> : <CodeBlock {...props} />;
 }

package/lib/theme/MDXComponents/Details.js

@@ -11,7 +11,7 @@ export default function MDXDetails(props) {
   // Split summary item from the rest to pass it as a separate prop to the
   // Details theme component
   const summary = items.find(
-    (item) => React.isValidElement(item) && item.props?.mdxType === 'summary',
+    (item) => React.isValidElement(item) && item.type === 'summary',
   );
   const children = <>{items.filter((item) => item !== summary)}</>;
   return (

package/lib/theme/MDXComponents/Pre.d.ts

@@ -4,6 +4,6 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-/// <reference types="react" />
+import { type ReactNode } from 'react';
 import type { Props } from '@theme/MDXComponents/Pre';
-export default function MDXPre(props: Props): JSX.Element;
+export default function MDXPre(props: Props): ReactNode | undefined;

package/lib/theme/MDXComponents/Pre.js

@@ -4,16 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {isValidElement} from 'react';
-import CodeBlock from '@theme/CodeBlock';
+import React from 'react';
 export default function MDXPre(props) {
-  return (
-    <CodeBlock
-      // If this pre is created by a ``` fenced codeblock, unwrap the children
-      {...(isValidElement(props.children) &&
-      props.children.props?.originalType === 'code'
-        ? props.children.props
-        : {...props})}
-    />
-  );
+  // With MDX 2, this element is only used for fenced code blocks
+  // It always receives a MDXComponents/Code as children
+  return <>{props.children}</>;
 }

package/lib/theme/MDXComponents/index.js

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import MDXHead from '@theme/MDXComponents/Head';
+import Head from '@docusaurus/Head';
 import MDXCode from '@theme/MDXComponents/Code';
 import MDXA from '@theme/MDXComponents/A';
 import MDXPre from '@theme/MDXComponents/Pre';
@@ -16,11 +16,11 @@ import MDXImg from '@theme/MDXComponents/Img';
 import Admonition from '@theme/Admonition';
 import Mermaid from '@theme/Mermaid';
 const MDXComponents = {
-  head: MDXHead,
+  Head,
+  Details: MDXDetails,
   code: MDXCode,
   a: MDXA,
   pre: MDXPre,
-  details: MDXDetails,
   ul: MDXUl,
   img: MDXImg,
   h1: (props) => <MDXHeading as="h1" {...props} />,

package/lib/theme/MDXContent/index.js

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
+// @ts-expect-error: TODO see https://github.com/microsoft/TypeScript/issues/49721
 import {MDXProvider} from '@mdx-js/react';
 import MDXComponents from '@theme/MDXComponents';
 export default function MDXContent({children}) {