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

package/src/theme/MDXPage/index.tsx

@@ -15,6 +15,7 @@ import {
 import Layout from '@theme/Layout';
 import MDXContent from '@theme/MDXContent';
 import TOC from '@theme/TOC';
+import Unlisted from '@theme/Unlisted';
 import type {Props} from '@theme/MDXPage';
 
 import styles from './styles.module.css';
@@ -22,10 +23,15 @@ import styles from './styles.module.css';
 export default function MDXPage(props: Props): JSX.Element {
   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
@@ -33,11 +39,17 @@ export default function MDXPage(props: Props): JSX.Element {
         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/src/theme/NavbarItem/DocNavbarItem.tsx

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

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/SiteMetadata/index.tsx

@@ -16,6 +16,7 @@ import {
   keyboardFocusedClassName,
 } from '@docusaurus/theme-common/internal';
 import {useLocation} from '@docusaurus/router';
+import {applyTrailingSlash} from '@docusaurus/utils-common';
 import SearchMetadata from '@theme/SearchMetadata';
 
 // TODO move to SiteMetadataDefaults or theme-common ?
@@ -24,10 +25,19 @@ import SearchMetadata from '@theme/SearchMetadata';
 // See https://github.com/facebook/docusaurus/issues/3317
 function AlternateLangHeaders(): JSX.Element {
   const {
-    i18n: {defaultLocale, localeConfigs},
+    i18n: {currentLocale, defaultLocale, localeConfigs},
   } = useDocusaurusContext();
   const alternatePageUtils = useAlternatePageUtils();
 
+  const currentHtmlLang = localeConfigs[currentLocale]!.htmlLang;
+
+  // HTML lang is a BCP 47 tag, but the Open Graph protocol requires
+  // using underscores instead of dashes.
+  // See https://ogp.me/#optional
+  // See https://en.wikipedia.org/wiki/IETF_language_tag)
+  const bcp47ToOpenGraphLocale = (code: string): string =>
+    code.replace('-', '_');
+
   // Note: it is fine to use both "x-default" and "en" to target the same url
   // See https://www.searchviu.com/en/multiple-hreflang-tags-one-url/
   return (
@@ -51,6 +61,20 @@ function AlternateLangHeaders(): JSX.Element {
         })}
         hrefLang="x-default"
       />
+
+      <meta
+        property="og:locale"
+        content={bcp47ToOpenGraphLocale(currentHtmlLang)}
+      />
+      {Object.values(localeConfigs)
+        .filter((config) => currentHtmlLang !== config.htmlLang)
+        .map((config) => (
+          <meta
+            key={`meta-og-${config.htmlLang}`}
+            property="og:locale:alternate"
+            content={bcp47ToOpenGraphLocale(config.htmlLang)}
+          />
+        ))}
     </Head>
   );
 }
@@ -58,10 +82,19 @@ function AlternateLangHeaders(): JSX.Element {
 // Default canonical url inferred from current page location pathname
 function useDefaultCanonicalUrl() {
   const {
-    siteConfig: {url: siteUrl},
+    siteConfig: {url: siteUrl, baseUrl, trailingSlash},
   } = useDocusaurusContext();
+
+  // TODO using useLocation().pathname is not a super idea
+  // See https://github.com/facebook/docusaurus/issues/9170
   const {pathname} = useLocation();
-  return siteUrl + useBaseUrl(pathname);
+
+  const canonicalPathname = applyTrailingSlash(useBaseUrl(pathname), {
+    trailingSlash,
+    baseUrl,
+  });
+
+  return siteUrl + canonicalPathname;
 }
 
 // TODO move to SiteMetadataDefaults or theme-common ?

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,123 @@ 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;
+}
+
+// TODO remove before v4: Caution replaced by Warning
+// see https://github.com/facebook/docusaurus/issues/7558
+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/Warning' {
+  import type {Props as AdmonitionProps} from '@theme/Admonition';
+
+  export interface Props extends AdmonitionProps {}
+  export default function AdmonitionTypeWarning(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/Warning' {
+  import type {ComponentProps} from 'react';
+
+  export interface Props extends ComponentProps<'svg'> {}
+
+  export default function AdmonitionIconWarning(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 +489,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 +509,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 +530,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 +772,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 +870,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 +890,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 +898,20 @@ 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;
+  import type {MDXProvider} from '@mdx-js/react';
+
+  type MDXComponentsBase = ComponentProps<typeof MDXProvider>['components'];
+
+  export type MDXComponentsObject = MDXComponentsBase & {
+    readonly Head: typeof Head;
+    readonly details: typeof MDXDetails;
+
+    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 +1079,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 +1506,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';