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

package/lib/getSwizzleConfig.js

@@ -17,13 +17,6 @@ function getSwizzleConfig() {
                 },
                 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',
@@ -52,6 +45,13 @@ function getSwizzleConfig() {
                 },
                 description: 'The admonition tip icon',
             },
+            'Admonition/Icon/Warning': {
+                actions: {
+                    eject: 'safe',
+                    wrap: 'safe',
+                },
+                description: 'The admonition warning icon',
+            },
             'Admonition/Layout': {
                 actions: {
                     eject: 'safe',
@@ -101,6 +101,13 @@ function getSwizzleConfig() {
                 },
                 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',
@@ -166,7 +173,7 @@ function getSwizzleConfig() {
                     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/lib/options.js

@@ -277,6 +277,9 @@ const LogoSchema = utils_validation_1.Joi.object({
     style: utils_validation_1.Joi.object(),
     className: utils_validation_1.Joi.string(),
 });
+// Normalize prism language to lowercase
+// See https://github.com/facebook/docusaurus/issues/9012
+const PrismLanguage = utils_validation_1.Joi.string().custom((val) => val.toLowerCase());
 exports.ThemeConfigSchema = utils_validation_1.Joi.object({
     // TODO temporary (@alpha-58)
     // @ts-expect-error: forbidden
@@ -341,9 +344,9 @@ exports.ThemeConfigSchema = utils_validation_1.Joi.object({
             plain: utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.array(), utils_validation_1.Joi.object()).required(),
             styles: utils_validation_1.Joi.alternatives().try(utils_validation_1.Joi.array(), utils_validation_1.Joi.object()).required(),
         }),
-        defaultLanguage: utils_validation_1.Joi.string(),
+        defaultLanguage: PrismLanguage,
         additionalLanguages: utils_validation_1.Joi.array()
-            .items(utils_validation_1.Joi.string())
+            .items(PrismLanguage)
             .default(exports.DEFAULT_CONFIG.prism.additionalLanguages),
         magicComments: utils_validation_1.Joi.array()
             .items(utils_validation_1.Joi.object({

package/lib/theme/Admonition/Icon/{Caution.d.ts → Warning.d.ts}

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="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;

package/lib/theme/Admonition/Type/Caution.js

@@ -8,10 +8,10 @@ import React from 'react';
 import clsx from 'clsx';
 import Translate from '@docusaurus/Translate';
 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"
@@ -20,6 +20,8 @@ const defaultProps = {
     </Translate>
   ),
 };
+// TODO remove before v4: Caution replaced by Warning
+// see https://github.com/facebook/docusaurus/issues/7558
 export default function AdmonitionTypeCaution(props) {
   return (
     <AdmonitionLayout

package/lib/theme/Admonition/Type/Warning.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/Admonition/Type/Warning';
+export default function AdmonitionTypeWarning(props: Props): JSX.Element;

package/lib/theme/Admonition/Type/Warning.js

@@ -0,0 +1,32 @@
+/**
+ * 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 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) {
+  return (
+    <AdmonitionLayout
+      {...defaultProps}
+      {...props}
+      className={clsx(infimaClassName, props.className)}>
+      {props.children}
+    </AdmonitionLayout>
+  );
+}

package/lib/theme/Admonition/Types.js

@@ -8,13 +8,14 @@ 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';
 const admonitionTypes = {
   note: AdmonitionTypeNote,
   tip: AdmonitionTypeTip,
   info: AdmonitionTypeInfo,
-  caution: AdmonitionTypeCaution,
+  warning: AdmonitionTypeWarning,
   danger: AdmonitionTypeDanger,
 };
 // Undocumented legacy admonition type aliases
@@ -24,8 +25,7 @@ const admonitionAliases = {
   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 {
   ...admonitionTypes,

package/lib/theme/BlogLayout/index.js

@@ -22,7 +22,7 @@ export default function BlogLayout(props) {
               '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/lib/theme/BlogPostItem/Container/index.js

@@ -8,17 +8,26 @@ import React from 'react';
 import {useBaseUrlUtils} from '@docusaurus/useBaseUrl';
 import {useBlogPost} from '@docusaurus/theme-common/internal';
 export default function BlogPostItemContainer({children, className}) {
-  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/lib/theme/BlogPostItem/Header/Author/index.js

@@ -20,7 +20,12 @@ export default function BlogPostItemHeaderAuthor({author, className}) {
     <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/lib/theme/CodeBlock/Content/String.js

@@ -20,6 +20,12 @@ import CopyButton from '@theme/CodeBlock/CopyButton';
 import WordWrapButton from '@theme/CodeBlock/WordWrapButton';
 import Container from '@theme/CodeBlock/Container';
 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) {
+  return language?.toLowerCase();
+}
 export default function CodeBlockString({
   children,
   className: blockClassName = '',
@@ -31,8 +37,9 @@ 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();
   // We still parse the metastring in case we want to support more syntax in the

package/lib/theme/CodeBlock/CopyButton/index.js

@@ -6,7 +6,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 IconCopy from '@theme/Icon/Copy';

package/lib/theme/DocItem/index.js

@@ -10,7 +10,7 @@ import {DocProvider} from '@docusaurus/theme-common/internal';
 import DocItemMetadata from '@theme/DocItem/Metadata';
 import DocItemLayout from '@theme/DocItem/Layout';
 export default function DocItem(props) {
-  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/lib/theme/DocSidebar/Desktop/index.d.ts

@@ -6,6 +6,6 @@
  */
 import React from 'react';
 import type { Props } from '@theme/DocSidebar/Desktop';
-declare function DocSidebarDesktop({ path, sidebar, onCollapse, isHidden }: Props): JSX.Element;
+declare function DocSidebarDesktop({ path, sidebar, onCollapse, isHidden }: Props): React.JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof DocSidebarDesktop>;
 export default _default;

package/lib/theme/DocSidebar/Mobile/index.d.ts

@@ -6,6 +6,6 @@
  */
 import React from 'react';
 import type { Props } from '@theme/DocSidebar/Mobile';
-declare function DocSidebarMobile(props: Props): JSX.Element;
+declare function DocSidebarMobile(props: Props): React.JSX.Element;
 declare const _default: React.MemoExoticComponent<typeof DocSidebarMobile>;
 export default _default;

package/lib/theme/DocSidebarItem/Category/index.js

@@ -56,18 +56,28 @@ function useCategoryHrefWithSSRFallback(item) {
     return findFirstSidebarItemLink(item);
   }, [item, isBrowser]);
 }
-function CollapseButton({categoryLabel, onClick}) {
+function CollapseButton({collapsed, categoryLabel, 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}
@@ -162,6 +172,7 @@ export default function DocSidebarItemCategory({
         </Link>
         {href && collapsible && (
           <CollapseButton
+            collapsed={collapsed}
             categoryLabel={label}
             onClick={(e) => {
               e.preventDefault();

package/lib/theme/MDXComponents/Ul/index.js

@@ -8,6 +8,10 @@ import React from 'react';
 import clsx from 'clsx';
 import styles from './styles.module.css';
 function transformUlClassName(className) {
+  // 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/lib/theme/MDXComponents/index.js

@@ -17,6 +17,7 @@ import Admonition from '@theme/Admonition';
 import Mermaid from '@theme/Mermaid';
 const MDXComponents = {
   Head,
+  details: MDXDetails,
   Details: MDXDetails,
   code: MDXCode,
   a: MDXA,

package/lib/theme/MDXContent/index.js

@@ -5,7 +5,6 @@
  * 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/SiteMetadata/index.js

@@ -15,6 +15,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 ?
 // Useful for i18n/SEO
@@ -22,9 +23,15 @@ import SearchMetadata from '@theme/SearchMetadata';
 // See https://github.com/facebook/docusaurus/issues/3317
 function AlternateLangHeaders() {
   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) => 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 (
@@ -48,16 +55,36 @@ function AlternateLangHeaders() {
         })}
         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>
   );
 }
 // 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 ?
 function CanonicalUrlHeaders({permalink}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-beta.0",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,38 +20,38 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "3.0.0-alpha.0",
-    "@docusaurus/mdx-loader": "3.0.0-alpha.0",
-    "@docusaurus/module-type-aliases": "3.0.0-alpha.0",
-    "@docusaurus/plugin-content-blog": "3.0.0-alpha.0",
-    "@docusaurus/plugin-content-docs": "3.0.0-alpha.0",
-    "@docusaurus/plugin-content-pages": "3.0.0-alpha.0",
-    "@docusaurus/theme-common": "3.0.0-alpha.0",
-    "@docusaurus/theme-translations": "3.0.0-alpha.0",
-    "@docusaurus/types": "3.0.0-alpha.0",
-    "@docusaurus/utils": "3.0.0-alpha.0",
-    "@docusaurus/utils-common": "3.0.0-alpha.0",
-    "@docusaurus/utils-validation": "3.0.0-alpha.0",
+    "@docusaurus/core": "3.0.0-beta.0",
+    "@docusaurus/mdx-loader": "3.0.0-beta.0",
+    "@docusaurus/module-type-aliases": "3.0.0-beta.0",
+    "@docusaurus/plugin-content-blog": "3.0.0-beta.0",
+    "@docusaurus/plugin-content-docs": "3.0.0-beta.0",
+    "@docusaurus/plugin-content-pages": "3.0.0-beta.0",
+    "@docusaurus/theme-common": "3.0.0-beta.0",
+    "@docusaurus/theme-translations": "3.0.0-beta.0",
+    "@docusaurus/types": "3.0.0-beta.0",
+    "@docusaurus/utils": "3.0.0-beta.0",
+    "@docusaurus/utils-common": "3.0.0-beta.0",
+    "@docusaurus/utils-validation": "3.0.0-beta.0",
     "@mdx-js/react": "^2.1.5",
     "clsx": "^1.2.1",
-    "copy-text-to-clipboard": "^3.0.1",
+    "copy-text-to-clipboard": "^3.2.0",
     "infima": "0.2.0-alpha.43",
     "lodash": "^4.17.21",
     "nprogress": "^0.2.0",
-    "postcss": "^8.4.21",
+    "postcss": "^8.4.26",
     "prism-react-renderer": "^1.3.5",
     "prismjs": "^1.29.0",
     "react-router-dom": "^5.3.4",
-    "rtlcss": "^4.0.0",
-    "tslib": "^2.5.0",
+    "rtlcss": "^4.1.0",
+    "tslib": "^2.6.0",
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
     "@types/mdx-js__react": "^1.5.5",
     "@types/nprogress": "^0.2.0",
     "@types/prismjs": "^1.26.0",
-    "@types/rtlcss": "^3.5.0",
-    "fs-extra": "^11.1.0",
+    "@types/rtlcss": "^3.5.1",
+    "fs-extra": "^11.1.1",
     "react-test-renderer": "^18.0.0",
     "utility-types": "^3.10.0"
   },
@@ -62,5 +62,5 @@
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "7327f7ff880ed97ad7855744e59c9c55d467a950"
+  "gitHead": "27a1e90d9fff88af90ecad35bea16d4d7230482a"
 }

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

@@ -313,6 +313,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 +389,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/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

@@ -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();
 

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/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-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' {
@@ -891,8 +900,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;