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

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/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}) {

package/lib/theme/MDXPage/index.js

@@ -14,25 +14,37 @@ import {
 import Layout from '@theme/Layout';
 import MDXContent from '@theme/MDXContent';
 import TOC from '@theme/TOC';
+import Unlisted from '@theme/Unlisted';
 import styles from './styles.module.css';
 export default function MDXPage(props) {
   const {content: MDXPageContent} = props;
   const {
-    metadata: {title, description, frontMatter},
+    metadata: {title, description, frontMatter, unlisted},
+    assets,
   } = MDXPageContent;
-  const {wrapperClassName, hide_table_of_contents: hideTableOfContents} =
-    frontMatter;
+  const {
+    keywords,
+    wrapperClassName,
+    hide_table_of_contents: hideTableOfContents,
+  } = frontMatter;
+  const image = assets.image ?? frontMatter.image;
   return (
     <HtmlClassNameProvider
       className={clsx(
         wrapperClassName ?? ThemeClassNames.wrapper.mdxPages,
         ThemeClassNames.page.mdxPage,
       )}>
-      <PageMetadata title={title} description={description} />
       <Layout>
+        <PageMetadata
+          title={title}
+          description={description}
+          keywords={keywords}
+          image={image}
+        />
         <main className="container container--fluid margin-vert--lg">
           <div className={clsx('row', styles.mdxPageWrapper)}>
             <div className={clsx('col', !hideTableOfContents && 'col--8')}>
+              {unlisted && <Unlisted />}
               <article>
                 <MDXContent>
                   <MDXPageContent />

package/lib/theme/NavbarItem/DocNavbarItem.js

@@ -16,8 +16,9 @@ export default function DocNavbarItem({
 }) {
   const {activeDoc} = useActiveDocContext(docsPluginId);
   const doc = useLayoutDoc(docId, docsPluginId);
-  // Draft items are not displayed in the navbar.
-  if (doc === null) {
+  const pageActive = activeDoc?.path === doc?.path;
+  // Draft and unlisted items are not displayed in the navbar.
+  if (doc === null || (doc.unlisted && !pageActive)) {
     return null;
   }
   return (
@@ -25,7 +26,7 @@ export default function DocNavbarItem({
       exact
       {...props}
       isActive={() =>
-        activeDoc?.path === doc.path ||
+        pageActive ||
         (!!activeDoc?.sidebar && activeDoc.sidebar === doc.sidebar)
       }
       label={staticLabel ?? doc.id}

package/lib/theme/NavbarItem/LocaleDropdownNavbarItem/index.d.ts

@@ -6,4 +6,4 @@
  */
 /// <reference types="react" />
 import type { Props } from '@theme/NavbarItem/LocaleDropdownNavbarItem';
-export default function LocaleDropdownNavbarItem({ mobile, dropdownItemsBefore, dropdownItemsAfter, ...props }: Props): JSX.Element;
+export default function LocaleDropdownNavbarItem({ mobile, dropdownItemsBefore, dropdownItemsAfter, queryString, ...props }: Props): JSX.Element;

package/lib/theme/NavbarItem/LocaleDropdownNavbarItem/index.js

@@ -16,6 +16,7 @@ export default function LocaleDropdownNavbarItem({
   mobile,
   dropdownItemsBefore,
   dropdownItemsAfter,
+  queryString = '',
   ...props
 }) {
   const {
@@ -29,7 +30,7 @@ export default function LocaleDropdownNavbarItem({
       fullyQualified: false,
     })}`;
     // preserve ?search#hash suffix on locale switches
-    const to = `${baseTo}${search}${hash}`;
+    const to = `${baseTo}${search}${hash}${queryString}`;
     return {
       label: localeConfigs[locale].label,
       lang: localeConfigs[locale].htmlLang,

package/lib/theme/NotFound/Content/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/NotFound/Content';
+export default function NotFoundContent({ className }: Props): JSX.Element;

package/lib/theme/NotFound/Content/index.js

@@ -0,0 +1,42 @@
+/**
+ * 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 Translate from '@docusaurus/Translate';
+import Heading from '@theme/Heading';
+export default function NotFoundContent({className}) {
+  return (
+    <main className={clsx('container margin-vert--xl', className)}>
+      <div className="row">
+        <div className="col col--6 col--offset-3">
+          <Heading as="h1" className="hero__title">
+            <Translate
+              id="theme.NotFound.title"
+              description="The title of the 404 page">
+              Page Not Found
+            </Translate>
+          </Heading>
+          <p>
+            <Translate
+              id="theme.NotFound.p1"
+              description="The first paragraph of the 404 page">
+              We could not find what you were looking for.
+            </Translate>
+          </p>
+          <p>
+            <Translate
+              id="theme.NotFound.p2"
+              description="The 2nd paragraph of the 404 page">
+              Please contact the owner of the site that linked you to the
+              original URL and let them know their link is broken.
+            </Translate>
+          </p>
+        </div>
+      </div>
+    </main>
+  );
+}

package/lib/theme/{NotFound.d.ts → NotFound/index.d.ts}

@@ -5,4 +5,4 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-export default function NotFound(): JSX.Element;
+export default function Index(): JSX.Element;

package/lib/theme/NotFound/index.js

@@ -0,0 +1,25 @@
+/**
+ * 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 {translate} from '@docusaurus/Translate';
+import {PageMetadata} from '@docusaurus/theme-common';
+import Layout from '@theme/Layout';
+import NotFoundContent from '@theme/NotFound/Content';
+export default function Index() {
+  const title = translate({
+    id: 'theme.NotFound.title',
+    message: 'Page Not Found',
+  });
+  return (
+    <>
+      <PageMetadata title={title} />
+      <Layout>
+        <NotFoundContent />
+      </Layout>
+    </>
+  );
+}

package/lib/theme/TOCItems/Tree.js

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
+import Link from '@docusaurus/Link';
 // Recursive component rendering the toc tree
 function TOCItemTree({toc, className, linkClassName, isChild}) {
   if (!toc.length) {
@@ -14,12 +15,10 @@ function TOCItemTree({toc, className, linkClassName, isChild}) {
     <ul className={isChild ? undefined : className}>
       {toc.map((heading) => (
         <li key={heading.id}>
-          {/* eslint-disable-next-line jsx-a11y/control-has-associated-label */}
-          <a
-            href={`#${heading.id}`}
+          <Link
+            to={`#${heading.id}`}
             className={linkClassName ?? undefined}
             // Developer provided the HTML, so assume it's safe.
-            // eslint-disable-next-line react/no-danger
             dangerouslySetInnerHTML={{__html: heading.value}}
           />
           <TOCItemTree