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

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/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/Unlisted/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/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.0",
+  "version": "3.0.0-alpha.0",
   "description": "Classic theme for Docusaurus",
   "main": "lib/index.js",
   "types": "src/theme-classic.d.ts",
@@ -20,30 +20,30 @@
     "copy:watch": "node ../../admin/scripts/copyUntypedFiles.js --watch"
   },
   "dependencies": {
-    "@docusaurus/core": "2.4.0",
-    "@docusaurus/mdx-loader": "2.4.0",
-    "@docusaurus/module-type-aliases": "2.4.0",
-    "@docusaurus/plugin-content-blog": "2.4.0",
-    "@docusaurus/plugin-content-docs": "2.4.0",
-    "@docusaurus/plugin-content-pages": "2.4.0",
-    "@docusaurus/theme-common": "2.4.0",
-    "@docusaurus/theme-translations": "2.4.0",
-    "@docusaurus/types": "2.4.0",
-    "@docusaurus/utils": "2.4.0",
-    "@docusaurus/utils-common": "2.4.0",
-    "@docusaurus/utils-validation": "2.4.0",
-    "@mdx-js/react": "^1.6.22",
+    "@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",
+    "@mdx-js/react": "^2.1.5",
     "clsx": "^1.2.1",
     "copy-text-to-clipboard": "^3.0.1",
     "infima": "0.2.0-alpha.43",
     "lodash": "^4.17.21",
     "nprogress": "^0.2.0",
-    "postcss": "^8.4.14",
+    "postcss": "^8.4.21",
     "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.0.0",
+    "tslib": "^2.5.0",
     "utility-types": "^3.10.0"
   },
   "devDependencies": {
@@ -51,16 +51,16 @@
     "@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",
+    "fs-extra": "^11.1.0",
+    "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": "898b85ef134cc43bf3b1209aad0ca8cdcfb214c5"
+  "gitHead": "7327f7ff880ed97ad7855744e59c9c55d467a950"
 }

package/src/getSwizzleConfig.ts

@@ -12,6 +12,113 @@ import type {SwizzleConfig} from '@docusaurus/types';
 export default function getSwizzleConfig(): SwizzleConfig {
   return {
     components: {
+      'Admonition/Icon': {
+        actions: {
+          eject: 'safe',
+          wrap: 'forbidden', // Can't wrap a folder
+        },
+        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',
+          wrap: 'safe',
+        },
+        description: 'The admonition danger icon',
+      },
+      'Admonition/Icon/Info': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The admonition info icon',
+      },
+      'Admonition/Icon/Note': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The admonition note icon',
+      },
+      'Admonition/Icon/Tip': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description: 'The admonition tip icon',
+      },
+      'Admonition/Layout': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The standard admonition layout applied to all default admonition types',
+      },
+      'Admonition/Type': {
+        actions: {
+          eject: 'safe',
+          wrap: 'forbidden',
+        },
+        description:
+          'The folder containing all the admonition type components.',
+      },
+      'Admonition/Type/Caution': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component responsible for rendering a :::caution admonition type',
+      },
+      'Admonition/Type/Danger': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component responsible for rendering a :::danger admonition type',
+      },
+      'Admonition/Type/Info': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component responsible for rendering a :::info admonition type',
+      },
+      'Admonition/Type/Note': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component responsible for rendering a :::note admonition type',
+      },
+      'Admonition/Type/Tip': {
+        actions: {
+          eject: 'safe',
+          wrap: 'safe',
+        },
+        description:
+          'The component responsible for rendering a :::tip admonition type',
+      },
+      'Admonition/Types': {
+        actions: {
+          eject: 'safe',
+          // TODO the swizzle CLI should provide a way to wrap such objects
+          wrap: 'forbidden',
+        },
+        description:
+          'The object mapping admonition type to a React component.\nUse it to add custom admonition type components, or replace existing ones.\nCan be ejected or wrapped (only manually, see our documentation).',
+      },
       CodeBlock: {
         actions: {
           eject: 'safe',
@@ -205,14 +312,6 @@ export default function getSwizzleConfig(): SwizzleConfig {
         },
         description: 'The component used to render <details> tags in MDX',
       },
-      'MDXComponents/Head': {
-        actions: {
-          eject: 'forbidden',
-          wrap: 'forbidden',
-        },
-        description:
-          'Technical component used to assign metadata (generally for SEO purpose) to the current MDX document',
-      },
       'MDXComponents/Heading': {
         actions: {
           eject: 'safe',

package/src/index.ts

@@ -26,7 +26,10 @@ const ContextReplacementPlugin = requireFromDocusaurusCore(
 // Need to be inlined to prevent dark mode FOUC
 // Make sure the key is the same as the one in `/theme/hooks/useTheme.js`
 const ThemeStorageKey = 'theme';
+// Support for ?docusaurus-theme=dark
 const ThemeQueryStringKey = 'docusaurus-theme';
+// Support for ?docusaurus-data-mode=embed&docusaurus-data-myAttr=42
+const DataQueryStringPrefixKey = 'docusaurus-data-';
 
 const noFlashColorMode = ({
   defaultMode,
@@ -42,19 +45,15 @@ const noFlashColorMode = ({
   }
 
   function getQueryStringTheme() {
-    var theme = null;
     try {
-      theme = new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
+      return new URLSearchParams(window.location.search).get('${ThemeQueryStringKey}')
     } catch(e) {}
-    return theme;
   }
 
   function getStoredTheme() {
-    var theme = null;
     try {
-      theme = localStorage.getItem('${ThemeStorageKey}');
+      return localStorage.getItem('${ThemeStorageKey}');
     } catch (err) {}
-    return theme;
   }
 
   var initialTheme = getQueryStringTheme() || getStoredTheme();
@@ -77,6 +76,21 @@ const noFlashColorMode = ({
   }
 })();`;
 
+/* language=js */
+const DataAttributeQueryStringInlineJavaScript = `
+(function() {
+  try {
+    const entries = new URLSearchParams(window.location.search).entries();
+    for (var [searchKey, value] of entries) {
+      if (searchKey.startsWith('${DataQueryStringPrefixKey}')) {
+        var key = searchKey.replace('${DataQueryStringPrefixKey}',"data-")
+        document.documentElement.setAttribute(key, value);
+      }
+    }
+  } catch(e) {}
+})();
+`;
+
 // Duplicated constant. Unfortunately we can't import it from theme-common, as
 // we need to support older nodejs versions without ESM support
 // TODO: import from theme-common once we only support Node.js with ESM support
@@ -205,6 +219,7 @@ export default function themeClassic(
             tagName: 'script',
             innerHTML: `
 ${noFlashColorMode(colorMode)}
+${DataAttributeQueryStringInlineJavaScript}
 ${announcementBar ? AnnouncementBarInlineJavaScript : ''}
             `,
           },

package/src/nprogress.ts

@@ -6,9 +6,10 @@
  */
 
 import nprogress from 'nprogress';
-import './nprogress.css';
 import type {ClientModule} from '@docusaurus/types';
 
+import './nprogress.css';
+
 nprogress.configure({showSpinner: false});
 
 const delay = 200;

package/src/options.ts

@@ -200,6 +200,7 @@ const LocaleDropdownNavbarItemSchema = NavbarItemBaseSchema.append({
   type: Joi.string().equal('localeDropdown').required(),
   dropdownItemsBefore: Joi.array().items(DropdownSubitemSchema).default([]),
   dropdownItemsAfter: Joi.array().items(DropdownSubitemSchema).default([]),
+  queryString: Joi.string(),
 });
 
 const SearchItemSchema = Joi.object({

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

@@ -0,0 +1,20 @@
+/**
+ * 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 type {Props} from '@theme/Admonition/Icon/Caution';
+
+export default function AdmonitionIconCaution(props: Props): JSX.Element {
+  return (
+    <svg viewBox="0 0 16 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M8.893 1.5c-.183-.31-.52-.5-.887-.5s-.703.19-.886.5L.138 13.499a.98.98 0 0 0 0 1.001c.193.31.53.501.886.501h13.964c.367 0 .704-.19.877-.5a1.03 1.03 0 0 0 .01-1.002L8.893 1.5zm.133 11.497H6.987v-2.003h2.039v2.003zm0-3.004H6.987V5.987h2.039v4.006z"
+      />
+    </svg>
+  );
+}

package/src/theme/Admonition/Icon/Danger.tsx

@@ -0,0 +1,20 @@
+/**
+ * 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 type {Props} from '@theme/Admonition/Icon/Danger';
+
+export default function AdmonitionIconDanger(props: Props): JSX.Element {
+  return (
+    <svg viewBox="0 0 12 16" {...props}>
+      <path
+        fillRule="evenodd"
+        d="M5.05.31c.81 2.17.41 3.38-.52 4.31C3.55 5.67 1.98 6.45.9 7.98c-1.45 2.05-1.7 6.53 3.53 7.7-2.2-1.16-2.67-4.52-.3-6.61-.61 2.03.53 3.33 1.94 2.86 1.39-.47 2.3.53 2.27 1.67-.02.78-.31 1.44-1.13 1.81 3.42-.59 4.78-3.42 4.78-5.56 0-2.84-2.53-3.22-1.25-5.61-1.52.13-2.03 1.13-1.89 2.75.09 1.08-1.02 1.8-1.86 1.33-.67-.41-.66-1.19-.06-1.78C8.18 5.31 8.68 2.45 5.05.32L5.03.3l.02.01z"
+      />
+    </svg>
+  );
+}