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

package/src/theme/NavbarItem/LocaleDropdownNavbarItem/index.tsx

@@ -21,6 +21,7 @@ export default function LocaleDropdownNavbarItem({
   mobile,
   dropdownItemsBefore,
   dropdownItemsAfter,
+  queryString = '',
   ...props
 }: Props): JSX.Element {
   const {
@@ -35,7 +36,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/src/theme/NotFound/Content/index.tsx

@@ -0,0 +1,45 @@
+/**
+ * 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 type {Props} from '@theme/NotFound/Content';
+import Heading from '@theme/Heading';
+
+export default function NotFoundContent({className}: Props): JSX.Element {
+  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/src/theme/NotFound/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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(): JSX.Element {
+  const title = translate({
+    id: 'theme.NotFound.title',
+    message: 'Page Not Found',
+  });
+  return (
+    <>
+      <PageMetadata title={title} />
+      <Layout>
+        <NotFoundContent />
+      </Layout>
+    </>
+  );
+}

package/src/theme/SkipToContent/index.tsx

@@ -7,7 +7,6 @@
 
 import React from 'react';
 import {SkipToContentLink} from '@docusaurus/theme-common';
-
 import styles from './styles.module.css';
 
 export default function SkipToContent(): JSX.Element {

package/src/theme/TOCItems/Tree.tsx

@@ -6,6 +6,7 @@
  */
 
 import React from 'react';
+import Link from '@docusaurus/Link';
 import type {Props} from '@theme/TOCItems/Tree';
 
 // Recursive component rendering the toc tree
@@ -22,12 +23,10 @@ function TOCItemTree({
     <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

package/src/theme/Tabs/index.tsx

@@ -10,6 +10,7 @@ import clsx from 'clsx';
 import {
   useScrollPositionBlocker,
   useTabs,
+  sanitizeTabsChildren,
   type TabItemProps,
 } from '@docusaurus/theme-common/internal';
 import useIsBrowser from '@docusaurus/useIsBrowser';
@@ -152,7 +153,8 @@ export default function Tabs(props: Props): JSX.Element {
       // Remount tabs after hydration
       // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
       key={String(isBrowser)}
-      {...props}
-    />
+      {...props}>
+      {sanitizeTabsChildren(props.children)}
+    </TabsComponent>
   );
 }

package/src/theme/TagsListByLetter/index.tsx

@@ -9,13 +9,15 @@ import React from 'react';
 import {listTagsByLetters, type TagLetterEntry} from '@docusaurus/theme-common';
 import Tag from '@theme/Tag';
 import type {Props} from '@theme/TagsListByLetter';
-
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 
 function TagLetterEntryItem({letterEntry}: {letterEntry: TagLetterEntry}) {
   return (
     <article>
-      <h2>{letterEntry.letter}</h2>
+      <Heading as="h2" id={letterEntry.letter}>
+        {letterEntry.letter}
+      </Heading>
       <ul className="padding--none">
         {letterEntry.tags.map((tag) => (
           <li key={tag.permalink} className={styles.tag}>

package/src/theme/ThemedImage/index.tsx

@@ -6,44 +6,21 @@
  */
 
 import React from 'react';
-import clsx from 'clsx';
-import useIsBrowser from '@docusaurus/useIsBrowser';
-import {useColorMode} from '@docusaurus/theme-common';
+import {ThemedComponent} from '@docusaurus/theme-common';
 import type {Props} from '@theme/ThemedImage';
 
-import styles from './styles.module.css';
-
 export default function ThemedImage(props: Props): JSX.Element {
-  const isBrowser = useIsBrowser();
-  const {colorMode} = useColorMode();
-  const {sources, className, alt, ...propsRest} = props;
-
-  type SourceName = keyof Props['sources'];
-
-  const clientThemes: SourceName[] =
-    colorMode === 'dark' ? ['dark'] : ['light'];
-
-  const renderedSourceNames: SourceName[] = isBrowser
-    ? clientThemes
-    : // We need to render both images on the server to avoid flash
-      // See https://github.com/facebook/docusaurus/pull/3730
-      ['light', 'dark'];
-
+  const {sources, className: parentClassName, alt, ...propsRest} = props;
   return (
-    <>
-      {renderedSourceNames.map((sourceName) => (
+    <ThemedComponent className={parentClassName}>
+      {({theme, className}) => (
         <img
-          key={sourceName}
-          src={sources[sourceName]}
+          src={sources[theme]}
           alt={alt}
-          className={clsx(
-            styles.themedImage,
-            styles[`themedImage--${sourceName}`],
-            className,
-          )}
+          className={className}
           {...propsRest}
         />
-      ))}
-    </>
+      )}
+    </ThemedComponent>
   );
 }

package/src/theme/Unlisted/index.tsx

@@ -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 {
+  ThemeClassNames,
+  UnlistedBannerTitle,
+  UnlistedBannerMessage,
+  UnlistedMetadata,
+} from '@docusaurus/theme-common';
+import Admonition from '@theme/Admonition';
+import type {Props} from '@theme/Unlisted';
+
+function UnlistedBanner({className}: Props) {
+  return (
+    <Admonition
+      type="caution"
+      title={<UnlistedBannerTitle />}
+      className={clsx(className, ThemeClassNames.common.unlistedBanner)}>
+      <UnlistedBannerMessage />
+    </Admonition>
+  );
+}
+
+export default function Unlisted(props: Props): JSX.Element | null {
+  return (
+    <>
+      {/*
+      Unlisted metadata declared here for simplicity.
+      Ensures we never forget to add the correct noindex metadata.
+      Also gives a central place for user to swizzle override default metadata.
+      */}
+      <UnlistedMetadata />
+      <UnlistedBanner {...props} />
+    </>
+  );
+}

package/src/theme/prism-include-languages.ts

@@ -7,6 +7,7 @@
 
 import siteConfig from '@generated/docusaurus.config';
 import type * as PrismNamespace from 'prismjs';
+import type {Optional} from 'utility-types';
 
 export default function prismIncludeLanguages(
   PrismObject: typeof PrismNamespace,
@@ -29,5 +30,5 @@ export default function prismIncludeLanguages(
     require(`prismjs/components/prism-${lang}`);
   });
 
-  delete (globalThis as Global & {Prism?: typeof PrismNamespace}).Prism;
+  delete (globalThis as Optional<typeof globalThis, 'Prism'>).Prism;
 }

package/src/theme-classic.d.ts

@@ -44,13 +44,114 @@ declare module '@theme/Admonition' {
 
   export interface Props {
     readonly children: ReactNode;
-    readonly type: 'note' | 'tip' | 'danger' | 'info' | 'caution';
+    readonly type: string;
     readonly icon?: ReactNode;
     readonly title?: ReactNode;
+    readonly className?: string;
   }
+
   export default function Admonition(props: Props): JSX.Element;
 }
 
+declare module '@theme/Admonition/Type/Note' {
+  import type {Props as AdmonitionProps} from '@theme/Admonition';
+
+  export interface Props extends AdmonitionProps {}
+  export default function AdmonitionTypeNote(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Type/Info' {
+  import type {Props as AdmonitionProps} from '@theme/Admonition';
+
+  export interface Props extends AdmonitionProps {}
+  export default function AdmonitionTypeInfo(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Type/Tip' {
+  import type {Props as AdmonitionProps} from '@theme/Admonition';
+
+  export interface Props extends AdmonitionProps {}
+  export default function AdmonitionTypeTip(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Type/Caution' {
+  import type {Props as AdmonitionProps} from '@theme/Admonition';
+
+  export interface Props extends AdmonitionProps {}
+  export default function AdmonitionTypeCaution(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Type/Danger' {
+  import type {Props as AdmonitionProps} from '@theme/Admonition';
+
+  export interface Props extends AdmonitionProps {}
+  export default function AdmonitionTypeDanger(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Types' {
+  import type {ComponentType} from 'react';
+  import type {Props} from '@theme/Admonition';
+
+  const AdmonitionTypes: {
+    [admonitionType: string]: ComponentType<Props>;
+  };
+
+  export default AdmonitionTypes;
+}
+
+declare module '@theme/Admonition/Layout' {
+  import type {ReactNode} from 'react';
+
+  export interface Props {
+    readonly children: ReactNode;
+    readonly type: string;
+    readonly icon?: ReactNode;
+    readonly title?: ReactNode;
+    readonly className?: string;
+  }
+  export default function AdmonitionLayout(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Icon/Note' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function AdmonitionIconNote(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Icon/Tip' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function AdmonitionIconTip(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Icon/Caution' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function AdmonitionIconCaution(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Icon/Danger' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function AdmonitionIconDanger(props: Props): JSX.Element;
+}
+
+declare module '@theme/Admonition/Icon/Info' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function AdmonitionIconInfo(props: Props): JSX.Element;
+}
+
 declare module '@theme/AnnouncementBar' {
   export default function AnnouncementBar(): JSX.Element | null;
 }
@@ -379,17 +480,17 @@ declare module '@theme/DocItem/Footer' {
   export default function DocItemFooter(): JSX.Element;
 }
 
-declare module '@theme/DocPage/Layout' {
+declare module '@theme/DocRoot/Layout' {
   import type {ReactNode} from 'react';
 
   export interface Props {
     readonly children: ReactNode;
   }
 
-  export default function DocPageLayout(props: Props): JSX.Element;
+  export default function DocRootLayout(props: Props): JSX.Element;
 }
 
-declare module '@theme/DocPage/Layout/Sidebar' {
+declare module '@theme/DocRoot/Layout/Sidebar' {
   import type {Dispatch, SetStateAction} from 'react';
   import type {PropSidebar} from '@docusaurus/plugin-content-docs';
 
@@ -399,20 +500,20 @@ declare module '@theme/DocPage/Layout/Sidebar' {
     readonly setHiddenSidebarContainer: Dispatch<SetStateAction<boolean>>;
   }
 
-  export default function DocPageLayoutSidebar(props: Props): JSX.Element;
+  export default function DocRootLayoutSidebar(props: Props): JSX.Element;
 }
 
-declare module '@theme/DocPage/Layout/Sidebar/ExpandButton' {
+declare module '@theme/DocRoot/Layout/Sidebar/ExpandButton' {
   export interface Props {
     toggleSidebar: () => void;
   }
 
-  export default function DocPageLayoutSidebarExpandButton(
+  export default function DocRootLayoutSidebarExpandButton(
     props: Props,
   ): JSX.Element;
 }
 
-declare module '@theme/DocPage/Layout/Main' {
+declare module '@theme/DocRoot/Layout/Main' {
   import type {ReactNode} from 'react';
 
   export interface Props {
@@ -420,7 +521,7 @@ declare module '@theme/DocPage/Layout/Main' {
     readonly children: ReactNode;
   }
 
-  export default function DocPageLayoutMain(props: Props): JSX.Element;
+  export default function DocRootLayoutMain(props: Props): JSX.Element;
 }
 
 declare module '@theme/DocPaginator' {
@@ -662,6 +763,14 @@ declare module '@theme/Heading' {
   export default function Heading(props: Props): JSX.Element;
 }
 
+declare module '@theme/NotFound/Content' {
+  export interface Props {
+    readonly className?: string;
+  }
+
+  export default function NotFoundContent(props: Props): JSX.Element;
+}
+
 declare module '@theme/Layout' {
   import type {ReactNode} from 'react';
 
@@ -752,14 +861,6 @@ declare module '@theme/MDXComponents/Img' {
   export default function MDXImg(props: Props): JSX.Element;
 }
 
-declare module '@theme/MDXComponents/Head' {
-  import type {ComponentProps} from 'react';
-
-  export interface Props extends ComponentProps<'head'> {}
-
-  export default function MDXHead(props: Props): JSX.Element;
-}
-
 declare module '@theme/MDXComponents/Heading' {
   import type {ComponentProps} from 'react';
   import type Heading from '@theme/Heading';
@@ -780,7 +881,6 @@ declare module '@theme/MDXComponents/Pre' {
 declare module '@theme/MDXComponents' {
   import type {ComponentType, ComponentProps} from 'react';
 
-  import type MDXHead from '@theme/MDXComponents/Head';
   import type MDXCode from '@theme/MDXComponents/Code';
   import type MDXA from '@theme/MDXComponents/A';
   import type MDXPre from '@theme/MDXComponents/Pre';
@@ -789,13 +889,14 @@ declare module '@theme/MDXComponents' {
   import type MDXImg from '@theme/MDXComponents/Img';
   import type Admonition from '@theme/Admonition';
   import type Mermaid from '@theme/Mermaid';
+  import type Head from '@docusaurus/Head';
 
   export type MDXComponentsObject = {
-    readonly head: typeof MDXHead;
+    readonly Head: typeof Head;
+    readonly Details: typeof MDXDetails;
     readonly code: typeof MDXCode;
     readonly a: typeof MDXA;
     readonly pre: typeof MDXPre;
-    readonly details: typeof MDXDetails;
     readonly ul: typeof MDXUl;
     readonly img: typeof MDXImg;
     readonly h1: (props: ComponentProps<'h1'>) => JSX.Element;
@@ -963,6 +1064,7 @@ declare module '@theme/NavbarItem/LocaleDropdownNavbarItem' {
   export interface Props extends DropdownNavbarItemProps {
     readonly dropdownItemsBefore: LinkLikeNavbarItemProps[];
     readonly dropdownItemsAfter: LinkLikeNavbarItemProps[];
+    readonly queryString?: string;
   }
 
   export default function LocaleDropdownNavbarItem(props: Props): JSX.Element;
@@ -1389,6 +1491,14 @@ declare module '@theme/Tag' {
   export default function Tag(props: Props): JSX.Element;
 }
 
+declare module '@theme/Unlisted' {
+  export interface Props {
+    className?: string;
+  }
+
+  export default function Unlisted(props: Props): JSX.Element;
+}
+
 declare module '@theme/prism-include-languages' {
   import type * as PrismNamespace from 'prismjs';
 

package/lib/theme/DocPage/index.js

@@ -1,67 +0,0 @@
-/**
- * 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,
-  PageMetadata,
-} from '@docusaurus/theme-common';
-import {
-  docVersionSearchTag,
-  DocsSidebarProvider,
-  DocsVersionProvider,
-  useDocRouteMetadata,
-} from '@docusaurus/theme-common/internal';
-import DocPageLayout from '@theme/DocPage/Layout';
-import NotFound from '@theme/NotFound';
-import SearchMetadata from '@theme/SearchMetadata';
-function DocPageMetadata(props) {
-  const {versionMetadata} = props;
-  return (
-    <>
-      <SearchMetadata
-        version={versionMetadata.version}
-        tag={docVersionSearchTag(
-          versionMetadata.pluginId,
-          versionMetadata.version,
-        )}
-      />
-      <PageMetadata>
-        {versionMetadata.noIndex && (
-          <meta name="robots" content="noindex, nofollow" />
-        )}
-      </PageMetadata>
-    </>
-  );
-}
-export default function DocPage(props) {
-  const {versionMetadata} = props;
-  const currentDocRouteMetadata = useDocRouteMetadata(props);
-  if (!currentDocRouteMetadata) {
-    return <NotFound />;
-  }
-  const {docElement, sidebarName, sidebarItems} = currentDocRouteMetadata;
-  return (
-    <>
-      <DocPageMetadata {...props} />
-      <HtmlClassNameProvider
-        className={clsx(
-          // TODO: it should be removed from here
-          ThemeClassNames.wrapper.docsPages,
-          ThemeClassNames.page.docsDocPage,
-          props.versionMetadata.className,
-        )}>
-        <DocsVersionProvider version={versionMetadata}>
-          <DocsSidebarProvider name={sidebarName} items={sidebarItems}>
-            <DocPageLayout>{docElement}</DocPageLayout>
-          </DocsSidebarProvider>
-        </DocsVersionProvider>
-      </HtmlClassNameProvider>
-    </>
-  );
-}

package/lib/theme/MDXComponents/Head.js

@@ -1,23 +0,0 @@
-/**
- * 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 Head from '@docusaurus/Head';
-// MDX elements are wrapped through the MDX pragma. In some cases (notably usage
-// with Head/Helmet) we need to unwrap those elements.
-function unwrapMDXElement(element) {
-  if (element.props?.mdxType && element.props.originalType) {
-    const {mdxType, originalType, ...newProps} = element.props;
-    return React.createElement(element.props.originalType, newProps);
-  }
-  return element;
-}
-export default function MDXHead(props) {
-  const unwrappedChildren = React.Children.map(props.children, (child) =>
-    React.isValidElement(child) ? unwrapMDXElement(child) : child,
-  );
-  return <Head {...props}>{unwrappedChildren}</Head>;
-}

package/lib/theme/NotFound.js

@@ -1,52 +0,0 @@
-/**
- * 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, {translate} from '@docusaurus/Translate';
-import {PageMetadata} from '@docusaurus/theme-common';
-import Layout from '@theme/Layout';
-export default function NotFound() {
-  return (
-    <>
-      <PageMetadata
-        title={translate({
-          id: 'theme.NotFound.title',
-          message: 'Page Not Found',
-        })}
-      />
-      <Layout>
-        <main className="container margin-vert--xl">
-          <div className="row">
-            <div className="col col--6 col--offset-3">
-              <h1 className="hero__title">
-                <Translate
-                  id="theme.NotFound.title"
-                  description="The title of the 404 page">
-                  Page Not Found
-                </Translate>
-              </h1>
-              <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>
-      </Layout>
-    </>
-  );
-}