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

package/src/getSwizzleConfig.ts

@@ -19,13 +19,6 @@ export default function getSwizzleConfig(): SwizzleConfig {
         },
         description: 'The folder containing all admonition icons',
       },
-      'Admonition/Icon/Caution': {
-        actions: {
-          eject: 'safe',
-          wrap: 'safe',
-        },
-        description: 'The admonition caution icon',
-      },
       'Admonition/Icon/Danger': {
         actions: {
           eject: 'safe',
@@ -54,6 +47,13 @@ export default function getSwizzleConfig(): SwizzleConfig {
         },
         description: 'The admonition tip icon',
       },
+      'Admonition/Icon/Warning': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The admonition warning icon',
+      },
       'Admonition/Layout': {
         actions: {
           eject: 'safe',
@@ -110,6 +110,14 @@ export default function getSwizzleConfig(): SwizzleConfig {
         description:
           'The component responsible for rendering a :::tip admonition type',
       },
+      'Admonition/Type/Warning': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component responsible for rendering a :::warning admonition type',
+      },
       'Admonition/Types': {
         actions: {
           eject: 'safe',
@@ -182,7 +190,7 @@ export default function getSwizzleConfig(): SwizzleConfig {
           eject: 'safe',
           wrap: 'safe',
         },
-        description: "The footer component of you site's layout",
+        description: "The footer component of your site's layout",
       },
       'Footer/Copyright': {
         actions: {

package/src/options.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import defaultPrismTheme from 'prism-react-renderer/themes/palenight';
+import {themes} from 'prism-react-renderer';
 import {Joi, URISchema} from '@docusaurus/utils-validation';
 import type {Options, PluginOptions} from '@docusaurus/theme-classic';
 import type {ThemeConfig} from '@docusaurus/theme-common';
@@ -14,6 +14,7 @@ import type {
   OptionValidationContext,
 } from '@docusaurus/types';
 
+const defaultPrismTheme = themes.palenight;
 const DEFAULT_DOCS_CONFIG: ThemeConfig['docs'] = {
   versionPersistence: 'localStorage',
   sidebar: {
@@ -313,6 +314,10 @@ const LogoSchema = Joi.object({
   className: Joi.string(),
 });
 
+// Normalize prism language to lowercase
+// See https://github.com/facebook/docusaurus/issues/9012
+const PrismLanguage = Joi.string().custom((val) => val.toLowerCase());
+
 export const ThemeConfigSchema = Joi.object<ThemeConfig>({
   // TODO temporary (@alpha-58)
   // @ts-expect-error: forbidden
@@ -385,9 +390,9 @@ export const ThemeConfigSchema = Joi.object<ThemeConfig>({
       plain: Joi.alternatives().try(Joi.array(), Joi.object()).required(),
       styles: Joi.alternatives().try(Joi.array(), Joi.object()).required(),
     }),
-    defaultLanguage: Joi.string(),
+    defaultLanguage: PrismLanguage,
     additionalLanguages: Joi.array()
-      .items(Joi.string())
+      .items(PrismLanguage)
       .default(DEFAULT_CONFIG.prism.additionalLanguages),
     magicComments: Joi.array()
       .items(

package/src/prism-include-languages.ts

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import Prism from 'prism-react-renderer/prism';
+import {Prism} from 'prism-react-renderer';
 import prismIncludeLanguages from '@theme/prism-include-languages';
 
 prismIncludeLanguages(Prism);

package/src/theme/Admonition/Icon/{Caution.tsx → Warning.tsx}

@@ -6,7 +6,7 @@
  */
 
 import React from 'react';
-import type {Props} from '@theme/Admonition/Icon/Caution';
+import type {Props} from '@theme/Admonition/Icon/Warning';
 
 export default function AdmonitionIconCaution(props: Props): JSX.Element {
   return (

package/src/theme/Admonition/Type/Caution.tsx

@@ -10,12 +10,12 @@ import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
 import type {Props} from '@theme/Admonition/Type/Caution';
 import AdmonitionLayout from '@theme/Admonition/Layout';
-import IconCaution from '@theme/Admonition/Icon/Caution';
+import IconWarning from '@theme/Admonition/Icon/Warning';
 
 const infimaClassName = 'alert alert--warning';
 
 const defaultProps = {
-  icon: <IconCaution />,
+  icon: <IconWarning />,
   title: (
     <Translate
       id="theme.admonition.caution"
@@ -25,6 +25,8 @@ const defaultProps = {
   ),
 };
 
+// TODO remove before v4: Caution replaced by Warning
+// see https://github.com/facebook/docusaurus/issues/7558
 export default function AdmonitionTypeCaution(props: Props): JSX.Element {
   return (
     <AdmonitionLayout

package/src/theme/Admonition/Type/Warning.tsx

@@ -0,0 +1,37 @@
+/**
+ * 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/Admonition/Type/Warning';
+import AdmonitionLayout from '@theme/Admonition/Layout';
+import IconWarning from '@theme/Admonition/Icon/Warning';
+
+const infimaClassName = 'alert alert--warning';
+
+const defaultProps = {
+  icon: <IconWarning />,
+  title: (
+    <Translate
+      id="theme.admonition.warning"
+      description="The default label used for the Warning admonition (:::warning)">
+      warning
+    </Translate>
+  ),
+};
+
+export default function AdmonitionTypeWarning(props: Props): JSX.Element {
+  return (
+    <AdmonitionLayout
+      {...defaultProps}
+      {...props}
+      className={clsx(infimaClassName, props.className)}>
+      {props.children}
+    </AdmonitionLayout>
+  );
+}

package/src/theme/Admonition/Types.tsx

@@ -9,15 +9,16 @@ import React from 'react';
 import AdmonitionTypeNote from '@theme/Admonition/Type/Note';
 import AdmonitionTypeTip from '@theme/Admonition/Type/Tip';
 import AdmonitionTypeInfo from '@theme/Admonition/Type/Info';
-import AdmonitionTypeCaution from '@theme/Admonition/Type/Caution';
+import AdmonitionTypeWarning from '@theme/Admonition/Type/Warning';
 import AdmonitionTypeDanger from '@theme/Admonition/Type/Danger';
+import AdmonitionTypeCaution from '@theme/Admonition/Type/Caution';
 import type AdmonitionTypes from '@theme/Admonition/Types';
 
 const admonitionTypes: typeof AdmonitionTypes = {
   note: AdmonitionTypeNote,
   tip: AdmonitionTypeTip,
   info: AdmonitionTypeInfo,
-  caution: AdmonitionTypeCaution,
+  warning: AdmonitionTypeWarning,
   danger: AdmonitionTypeDanger,
 };
 
@@ -28,8 +29,7 @@ const admonitionAliases: typeof AdmonitionTypes = {
   secondary: (props) => <AdmonitionTypeNote title="secondary" {...props} />,
   important: (props) => <AdmonitionTypeInfo title="important" {...props} />,
   success: (props) => <AdmonitionTypeTip title="success" {...props} />,
-  // TODO bad legacy mapping, warning is usually yellow, not red...
-  warning: (props) => <AdmonitionTypeDanger title="warning" {...props} />,
+  caution: AdmonitionTypeCaution,
 };
 
 export default {

package/src/theme/BlogLayout/index.tsx

@@ -27,7 +27,7 @@ export default function BlogLayout(props: Props): JSX.Element {
               'col--9 col--offset-1': !hasSidebar,
             })}
             itemScope
-            itemType="http://schema.org/Blog">
+            itemType="https://schema.org/Blog">
             {children}
           </main>
           {toc && <div className="col col--2">{toc}</div>}

package/src/theme/BlogPostItem/Container/index.tsx

@@ -14,17 +14,26 @@ export default function BlogPostItemContainer({
   children,
   className,
 }: Props): JSX.Element {
-  const {frontMatter, assets} = useBlogPost();
+  const {
+    frontMatter,
+    assets,
+    metadata: {description},
+  } = useBlogPost();
   const {withBaseUrl} = useBaseUrlUtils();
   const image = assets.image ?? frontMatter.image;
+  const keywords = frontMatter.keywords ?? [];
   return (
     <article
       className={className}
       itemProp="blogPost"
       itemScope
-      itemType="http://schema.org/BlogPosting">
+      itemType="https://schema.org/BlogPosting">
+      {description && <meta itemProp="description" content={description} />}
       {image && (
-        <meta itemProp="image" content={withBaseUrl(image, {absolute: true})} />
+        <link itemProp="image" href={withBaseUrl(image, {absolute: true})} />
+      )}
+      {keywords.length > 0 && (
+        <meta itemProp="keywords" content={keywords.join(',')} />
       )}
       {children}
     </article>

package/src/theme/BlogPostItem/Header/Author/index.tsx

@@ -28,7 +28,12 @@ export default function BlogPostItemHeaderAuthor({
     <div className={clsx('avatar margin-bottom--sm', className)}>
       {imageURL && (
         <MaybeLink href={link} className="avatar__photo-link">
-          <img className="avatar__photo" src={imageURL} alt={name} />
+          <img
+            className="avatar__photo"
+            src={imageURL}
+            alt={name}
+            itemProp="image"
+          />
         </MaybeLink>
       )}
 

package/src/theme/CodeBlock/Content/String.tsx

@@ -15,7 +15,7 @@ import {
   containsLineNumbers,
   useCodeWordWrap,
 } from '@docusaurus/theme-common/internal';
-import Highlight, {defaultProps, type Language} from 'prism-react-renderer';
+import {Highlight, type Language} from 'prism-react-renderer';
 import Line from '@theme/CodeBlock/Line';
 import CopyButton from '@theme/CodeBlock/CopyButton';
 import WordWrapButton from '@theme/CodeBlock/WordWrapButton';
@@ -24,6 +24,13 @@ import type {Props} from '@theme/CodeBlock/Content/String';
 
 import styles from './styles.module.css';
 
+// Prism languages are always lowercase
+// We want to fail-safe and allow both "php" and "PHP"
+// See https://github.com/facebook/docusaurus/issues/9012
+function normalizeLanguage(language: string | undefined): string | undefined {
+  return language?.toLowerCase();
+}
+
 export default function CodeBlockString({
   children,
   className: blockClassName = '',
@@ -35,8 +42,10 @@ export default function CodeBlockString({
   const {
     prism: {defaultLanguage, magicComments},
   } = useThemeConfig();
-  const language =
-    languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage;
+  const language = normalizeLanguage(
+    languageProp ?? parseLanguage(blockClassName) ?? defaultLanguage,
+  );
+
   const prismTheme = usePrismTheme();
   const wordWrap = useCodeWordWrap();
 
@@ -65,16 +74,16 @@ export default function CodeBlockString({
       {title && <div className={styles.codeBlockTitle}>{title}</div>}
       <div className={styles.codeBlockContent}>
         <Highlight
-          {...defaultProps}
           theme={prismTheme}
           code={code}
           language={(language ?? 'text') as Language}>
-          {({className, tokens, getLineProps, getTokenProps}) => (
+          {({className, style, tokens, getLineProps, getTokenProps}) => (
             <pre
               /* eslint-disable-next-line jsx-a11y/no-noninteractive-tabindex */
               tabIndex={0}
               ref={wordWrap.codeBlockRef}
-              className={clsx(className, styles.codeBlock, 'thin-scrollbar')}>
+              className={clsx(className, styles.codeBlock, 'thin-scrollbar')}
+              style={style}>
               <code
                 className={clsx(
                   styles.codeBlockLines,

package/src/theme/CodeBlock/CopyButton/index.tsx

@@ -7,7 +7,6 @@
 
 import React, {useCallback, useState, useRef, useEffect} from 'react';
 import clsx from 'clsx';
-// @ts-expect-error: TODO, we need to make theme-classic have type: module
 import copy from 'copy-text-to-clipboard';
 import {translate} from '@docusaurus/Translate';
 import type {Props} from '@theme/CodeBlock/CopyButton';

package/src/theme/DocItem/index.tsx

@@ -13,7 +13,7 @@ import DocItemLayout from '@theme/DocItem/Layout';
 import type {Props} from '@theme/DocItem';
 
 export default function DocItem(props: Props): JSX.Element {
-  const docHtmlClassName = `docs-doc-id-${props.content.metadata.unversionedId}`;
+  const docHtmlClassName = `docs-doc-id-${props.content.metadata.id}`;
   const MDXComponent = props.content;
   return (
     <DocProvider content={props.content}>

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

@@ -72,23 +72,35 @@ function useCategoryHrefWithSSRFallback(
 }
 
 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/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,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ComponentProps} from 'react';
 import Head from '@docusaurus/Head';
 import MDXCode from '@theme/MDXComponents/Code';
 import MDXA from '@theme/MDXComponents/A';
@@ -21,18 +21,19 @@ import type {MDXComponentsObject} from '@theme/MDXComponents';
 
 const MDXComponents: MDXComponentsObject = {
   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,
   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,
 };

package/src/theme/MDXContent/index.tsx

@@ -6,7 +6,6 @@
  */
 
 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';
 import type {Props} from '@theme/MDXContent';

package/src/theme/Navbar/Search/index.tsx

@@ -15,5 +15,9 @@ export default function NavbarSearch({
   children,
   className,
 }: Props): JSX.Element {
-  return <div className={clsx(className, styles.searchBox)}>{children}</div>;
+  return (
+    <div className={clsx(className, styles.navbarSearchContainer)}>
+      {children}
+    </div>
+  );
 }

package/src/theme/Navbar/Search/styles.module.css

@@ -5,15 +5,23 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+/*
+Workaround to avoid rendering empty search container
+See https://github.com/facebook/docusaurus/pull/9385
+*/
+.navbarSearchContainer:not(:has(> *)) {
+  display: none;
+}
+
 @media (max-width: 996px) {
-  .searchBox {
+  .navbarSearchContainer {
     position: absolute;
     right: var(--ifm-navbar-padding-horizontal);
   }
 }
 
 @media (min-width: 997px) {
-  .searchBox {
+  .navbarSearchContainer {
     padding: var(--ifm-navbar-item-padding-vertical)
       var(--ifm-navbar-item-padding-horizontal);
   }

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/prism-include-languages.ts

@@ -26,6 +26,10 @@ export default function prismIncludeLanguages(
   globalThis.Prism = PrismObject;
 
   additionalLanguages.forEach((lang) => {
+    if (lang === 'php') {
+      // eslint-disable-next-line global-require
+      require('prismjs/components/prism-markup-templating.js');
+    }
     // eslint-disable-next-line global-require, import/no-dynamic-require
     require(`prismjs/components/prism-${lang}`);
   });

package/src/theme-classic.d.ts

@@ -74,6 +74,8 @@ declare module '@theme/Admonition/Type/Tip' {
   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';
 
@@ -81,6 +83,13 @@ declare module '@theme/Admonition/Type/Caution' {
   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';
 
@@ -128,12 +137,12 @@ declare module '@theme/Admonition/Icon/Tip' {
   export default function AdmonitionIconTip(props: Props): JSX.Element;
 }
 
-declare module '@theme/Admonition/Icon/Caution' {
+declare module '@theme/Admonition/Icon/Warning' {
   import type {ComponentProps} from 'react';
 
   export interface Props extends ComponentProps<'svg'> {}
 
-  export default function AdmonitionIconCaution(props: Props): JSX.Element;
+  export default function AdmonitionIconWarning(props: Props): JSX.Element;
 }
 
 declare module '@theme/Admonition/Icon/Danger' {
@@ -391,23 +400,20 @@ declare module '@theme/CodeBlock/Content/String' {
 }
 
 declare module '@theme/CodeBlock/Line' {
-  import type {ComponentProps} from 'react';
-  import type Highlight from 'prism-react-renderer';
-
-  // Lib does not make this easy
-  type RenderProps = Parameters<
-    ComponentProps<typeof Highlight>['children']
-  >[0];
-  type GetLineProps = RenderProps['getLineProps'];
-  type GetTokenProps = RenderProps['getTokenProps'];
-  type Token = RenderProps['tokens'][number][number];
+  import type {
+    LineInputProps,
+    LineOutputProps,
+    Token,
+    TokenInputProps,
+    TokenOutputProps,
+  } from 'prism-react-renderer';
 
   export interface Props {
     readonly line: Token[];
     readonly classNames: string[] | undefined;
     readonly showLineNumbers: boolean;
-    readonly getLineProps: GetLineProps;
-    readonly getTokenProps: GetTokenProps;
+    readonly getLineProps: (input: LineInputProps) => LineOutputProps;
+    readonly getTokenProps: (input: TokenInputProps) => TokenOutputProps;
   }
 
   export default function CodeBlockLine(props: Props): JSX.Element;
@@ -891,8 +897,14 @@ declare module '@theme/MDXComponents' {
   import type Mermaid from '@theme/Mermaid';
   import type Head from '@docusaurus/Head';
 
-  export type MDXComponentsObject = {
+  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;