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

package/lib/theme/MDXComponents/Pre.js

@@ -4,16 +4,9 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import React, {isValidElement} from 'react';
-import CodeBlock from '@theme/CodeBlock';
+import React from 'react';
 export default function MDXPre(props) {
-  return (
-    <CodeBlock
-      // If this pre is created by a ``` fenced codeblock, unwrap the children
-      {...(isValidElement(props.children) &&
-      props.children.props?.originalType === 'code'
-        ? props.children.props
-        : {...props})}
-    />
-  );
+  // With MDX 2, this element is only used for fenced code blocks
+  // It always receives a MDXComponents/Code as children
+  return <>{props.children}</>;
 }

package/lib/theme/MDXComponents/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

@@ -5,7 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import MDXHead from '@theme/MDXComponents/Head';
+import Head from '@docusaurus/Head';
 import MDXCode from '@theme/MDXComponents/Code';
 import MDXA from '@theme/MDXComponents/A';
 import MDXPre from '@theme/MDXComponents/Pre';
@@ -16,11 +16,12 @@ import MDXImg from '@theme/MDXComponents/Img';
 import Admonition from '@theme/Admonition';
 import Mermaid from '@theme/Mermaid';
 const MDXComponents = {
-  head: MDXHead,
+  Head,
+  details: MDXDetails,
+  Details: MDXDetails,
   code: MDXCode,
   a: MDXA,
   pre: MDXPre,
-  details: MDXDetails,
   ul: MDXUl,
   img: MDXImg,
   h1: (props) => <MDXHeading as="h1" {...props} />,

package/lib/theme/MDXPage/index.js

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

package/lib/theme/NavbarItem/DocNavbarItem.js

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

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

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

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

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

package/lib/theme/NotFound/Content/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/// <reference types="react" />
+import type { Props } from '@theme/NotFound/Content';
+export default function NotFoundContent({ className }: Props): JSX.Element;

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

@@ -0,0 +1,42 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import clsx from 'clsx';
+import Translate from '@docusaurus/Translate';
+import Heading from '@theme/Heading';
+export default function NotFoundContent({className}) {
+  return (
+    <main className={clsx('container margin-vert--xl', className)}>
+      <div className="row">
+        <div className="col col--6 col--offset-3">
+          <Heading as="h1" className="hero__title">
+            <Translate
+              id="theme.NotFound.title"
+              description="The title of the 404 page">
+              Page Not Found
+            </Translate>
+          </Heading>
+          <p>
+            <Translate
+              id="theme.NotFound.p1"
+              description="The first paragraph of the 404 page">
+              We could not find what you were looking for.
+            </Translate>
+          </p>
+          <p>
+            <Translate
+              id="theme.NotFound.p2"
+              description="The 2nd paragraph of the 404 page">
+              Please contact the owner of the site that linked you to the
+              original URL and let them know their link is broken.
+            </Translate>
+          </p>
+        </div>
+      </div>
+    </main>
+  );
+}

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

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

package/lib/theme/NotFound/index.js

@@ -0,0 +1,25 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import React from 'react';
+import {translate} from '@docusaurus/Translate';
+import {PageMetadata} from '@docusaurus/theme-common';
+import Layout from '@theme/Layout';
+import NotFoundContent from '@theme/NotFound/Content';
+export default function Index() {
+  const title = translate({
+    id: 'theme.NotFound.title',
+    message: 'Page Not Found',
+  });
+  return (
+    <>
+      <PageMetadata title={title} />
+      <Layout>
+        <NotFoundContent />
+      </Layout>
+    </>
+  );
+}

package/lib/theme/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/lib/theme/TOCItems/Tree.js

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

package/lib/theme/Tabs/index.js

@@ -9,6 +9,7 @@ import clsx from 'clsx';
 import {
   useScrollPositionBlocker,
   useTabs,
+  sanitizeTabsChildren,
 } from '@docusaurus/theme-common/internal';
 import useIsBrowser from '@docusaurus/useIsBrowser';
 import styles from './styles.module.css';
@@ -119,7 +120,8 @@ export default function Tabs(props) {
       // Remount tabs after hydration
       // Temporary fix for https://github.com/facebook/docusaurus/issues/5653
       key={String(isBrowser)}
-      {...props}
-    />
+      {...props}>
+      {sanitizeTabsChildren(props.children)}
+    </TabsComponent>
   );
 }

package/lib/theme/TagsListByLetter/index.js

@@ -7,11 +7,14 @@
 import React from 'react';
 import {listTagsByLetters} from '@docusaurus/theme-common';
 import Tag from '@theme/Tag';
+import Heading from '@theme/Heading';
 import styles from './styles.module.css';
 function TagLetterEntryItem({letterEntry}) {
   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/lib/theme/ThemedImage/index.js

@@ -5,35 +5,19 @@
  * LICENSE file in the root directory of this source tree.
  */
 import React from 'react';
-import clsx from 'clsx';
-import useIsBrowser from '@docusaurus/useIsBrowser';
-import {useColorMode} from '@docusaurus/theme-common';
-import styles from './styles.module.css';
+import {ThemedComponent} from '@docusaurus/theme-common';
 export default function ThemedImage(props) {
-  const isBrowser = useIsBrowser();
-  const {colorMode} = useColorMode();
-  const {sources, className, alt, ...propsRest} = props;
-  const clientThemes = colorMode === 'dark' ? ['dark'] : ['light'];
-  const renderedSourceNames = 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/lib/theme/{MDXComponents/Head.d.ts → Unlisted/index.d.ts}

@@ -5,5 +5,5 @@
  * LICENSE file in the root directory of this source tree.
  */
 /// <reference types="react" />
-import type { Props } from '@theme/MDXComponents/Head';
-export default function MDXHead(props: Props): JSX.Element;
+import type { Props } from '@theme/Unlisted';
+export default function Unlisted(props: Props): JSX.Element | null;

package/lib/theme/Unlisted/index.js

@@ -0,0 +1,38 @@
+/**
+ * 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';
+function UnlistedBanner({className}) {
+  return (
+    <Admonition
+      type="caution"
+      title={<UnlistedBannerTitle />}
+      className={clsx(className, ThemeClassNames.common.unlistedBanner)}>
+      <UnlistedBannerMessage />
+    </Admonition>
+  );
+}
+export default function Unlisted(props) {
+  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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docusaurus/theme-classic",
-  "version": "2.4.1",
+  "version": "3.0.0-beta.0",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,47 +20,47 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "2.4.1",
-    "@docusaurus/mdx-loader": "2.4.1",
-    "@docusaurus/module-type-aliases": "2.4.1",
-    "@docusaurus/plugin-content-blog": "2.4.1",
-    "@docusaurus/plugin-content-docs": "2.4.1",
-    "@docusaurus/plugin-content-pages": "2.4.1",
-    "@docusaurus/theme-common": "2.4.1",
-    "@docusaurus/theme-translations": "2.4.1",
-    "@docusaurus/types": "2.4.1",
-    "@docusaurus/utils": "2.4.1",
-    "@docusaurus/utils-common": "2.4.1",
-    "@docusaurus/utils-validation": "2.4.1",
-    "@mdx-js/react": "^1.6.22",
+    "@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.14",
+    "postcss": "^8.4.26",
     "prism-react-renderer": "^1.3.5",
-    "prismjs": "^1.28.0",
-    "react-router-dom": "^5.3.3",
-    "rtlcss": "^3.5.0",
-    "tslib": "^2.4.0",
+    "prismjs": "^1.29.0",
+    "react-router-dom": "^5.3.4",
+    "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": "^10.1.0",
-    "react-test-renderer": "^17.0.2",
+    "@types/rtlcss": "^3.5.1",
+    "fs-extra": "^11.1.1",
+    "react-test-renderer": "^18.0.0",
     "utility-types": "^3.10.0"
   },
   "peerDependencies": {
-    "react": "^16.8.4 || ^17.0.0",
-    "react-dom": "^16.8.4 || ^17.0.0"
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0"
   },
   "engines": {
     "node": ">=16.14"
   },
-  "gitHead": "60e657d8ae5a4a9ed1c2d777f9defd882cc12681"
+  "gitHead": "27a1e90d9fff88af90ecad35bea16d4d7230482a"
 }