@docusaurus/theme-classic 2.1.0 → 2.3.0

package/lib/getSwizzleConfig.js

@@ -17,6 +17,13 @@ function getSwizzleConfig() {
                 },
                 description: 'The component used to render multi-line code blocks, generally used in Markdown files.',
             },
+            'CodeBlock/Content': {
+                actions: {
+                    eject: 'unsafe',
+                    wrap: 'forbidden',
+                },
+                description: 'The folder containing components responsible for rendering different types of CodeBlock content.',
+            },
             ColorModeToggle: {
                 actions: {
                     eject: 'safe',
@@ -24,6 +31,13 @@ function getSwizzleConfig() {
                 },
                 description: 'The color mode toggle to switch between light and dark mode.',
             },
+            'DocBreadcrumbs/Items': {
+                actions: {
+                    eject: 'unsafe',
+                    wrap: 'forbidden', // Can't wrap a folder
+                },
+                description: 'The components responsible for rendering the breadcrumb items',
+            },
             DocCardList: {
                 actions: {
                     eject: 'safe',
@@ -31,6 +45,16 @@ function getSwizzleConfig() {
                 },
                 description: 'The component responsible for rendering a list of sidebar items cards.\nNotable used on the category generated-index pages.',
             },
+            'DocItem/TOC': {
+                actions: {
+                    // Forbidden because it's a parent folder, makes the CLI crash atm
+                    // TODO the CLI should rather support --eject
+                    // Subfolders can be swizzled
+                    eject: 'forbidden',
+                    wrap: 'forbidden',
+                },
+                description: 'The DocItem TOC is not directly swizzle-able, but you can swizzle its sub-components.',
+            },
             DocSidebar: {
                 actions: {
                     eject: 'unsafe',
@@ -94,6 +118,16 @@ function getSwizzleConfig() {
                 },
                 description: 'The footer logo',
             },
+            Icon: {
+                actions: {
+                    // Forbidden because it's a parent folder, makes the CLI crash atm
+                    // TODO the CLI should rather support --eject
+                    // Subfolders can be swizzled
+                    eject: 'forbidden',
+                    wrap: 'forbidden',
+                },
+                description: 'The Icon folder is not directly swizzle-able, but you can swizzle its sub-components.',
+            },
             'Icon/Arrow': {
                 actions: {
                     eject: 'safe',
@@ -204,7 +238,7 @@ function getSwizzleConfig() {
                     eject: 'safe',
                     wrap: 'forbidden',
                 },
-                description: 'The Navbar item components mapping. Can be ejected to add custom navbar item types. See https://github.com/facebook/docusaurus/issues/7227.',
+                description: 'The Navbar item components mapping. Can be ejected to add custom navbar item types.\nSee https://github.com/facebook/docusaurus/issues/7227.',
             },
             NotFound: {
                 actions: {
@@ -222,6 +256,13 @@ function getSwizzleConfig() {
                 // By default it's an empty placeholder for the user to fill
                 description: 'The search bar component of your site, appearing in the navbar.',
             },
+            SkipToContent: {
+                actions: {
+                    eject: 'safe',
+                    wrap: 'safe',
+                },
+                description: 'The component responsible for implementing the accessibility "skip to content" link (https://www.w3.org/TR/WCAG20-TECHS/G1.html)',
+            },
             'prism-include-languages': {
                 actions: {
                     eject: 'safe',

package/lib/theme/AnnouncementBar/styles.module.css

@@ -15,8 +15,16 @@
   height: var(--docusaurus-announcement-bar-height);
   background-color: var(--ifm-color-white);
   color: var(--ifm-color-black);
+
+  /*
+  Unfortunately we can't make announcement bar render above the navbar
+  IE need to use border-bottom instead of shadow
+  See https://github.com/facebookincubator/infima/issues/275
+
   box-shadow: var(--ifm-global-shadow-lw);
-  z-index: calc(var(--ifm-z-index-fixed) + 1); /* just above the navbar */
+  z-index: calc(var(--ifm-z-index-fixed) + 1);
+  */
+  border-bottom: 1px solid var(--ifm-color-emphasis-100);
 }
 
 html[data-announcement-bar-initially-dismissed='true'] .announcementBar {

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

@@ -32,11 +32,9 @@ export default function CodeBlockLine({
           <span className={styles.codeLineContent}>{lineTokens}</span>
         </>
       ) : (
-        <>
-          {lineTokens}
-          <br />
-        </>
+        lineTokens
       )}
+      <br />
     </span>
   );
 }

package/lib/theme/ColorModeToggle/index.js

@@ -46,7 +46,8 @@ function ColorModeToggle({className, value, onChange}) {
         onClick={() => onChange(value === 'dark' ? 'light' : 'dark')}
         disabled={!isBrowser}
         title={title}
-        aria-label={title}>
+        aria-label={title}
+        aria-live="polite">
         <IconLightMode
           className={clsx(styles.toggleIcon, styles.lightToggleIcon)}
         />

package/lib/theme/DocBreadcrumbs/Items/Home/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 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" />
+export default function HomeBreadcrumbItem(): JSX.Element;

package/lib/theme/DocBreadcrumbs/Items/Home/index.js

@@ -0,0 +1,29 @@
+/**
+ * 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 Link from '@docusaurus/Link';
+import useBaseUrl from '@docusaurus/useBaseUrl';
+import {translate} from '@docusaurus/Translate';
+import IconHome from '@theme/Icon/Home';
+import styles from './styles.module.css';
+export default function HomeBreadcrumbItem() {
+  const homeHref = useBaseUrl('/');
+  return (
+    <li className="breadcrumbs__item">
+      <Link
+        aria-label={translate({
+          id: 'theme.docs.breadcrumbs.home',
+          message: 'Home page',
+          description: 'The ARIA label for the home page in the breadcrumbs',
+        })}
+        className="breadcrumbs__link"
+        href={homeHref}>
+        <IconHome className={styles.breadcrumbHomeIcon} />
+      </Link>
+    </li>
+  );
+}

package/lib/theme/DocBreadcrumbs/Items/Home/styles.module.css

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ */
+
+.breadcrumbHomeIcon {
+  position: relative;
+  top: 1px;
+  vertical-align: top;
+  height: 1.1rem;
+  width: 1.1rem;
+}

package/lib/theme/DocBreadcrumbs/index.js

@@ -12,9 +12,8 @@ import {
   useHomePageRoute,
 } from '@docusaurus/theme-common/internal';
 import Link from '@docusaurus/Link';
-import useBaseUrl from '@docusaurus/useBaseUrl';
 import {translate} from '@docusaurus/Translate';
-import IconHome from '@theme/Icon/Home';
+import HomeBreadcrumbItem from '@theme/DocBreadcrumbs/Items/Home';
 import styles from './styles.module.css';
 // TODO move to design system folder
 function BreadcrumbsItemLink({children, href, isLast}) {
@@ -56,23 +55,6 @@ function BreadcrumbsItem({children, active, index, addMicrodata}) {
     </li>
   );
 }
-function HomeBreadcrumbItem() {
-  const homeHref = useBaseUrl('/');
-  return (
-    <li className="breadcrumbs__item">
-      <Link
-        aria-label={translate({
-          id: 'theme.docs.breadcrumbs.home',
-          message: 'Home page',
-          description: 'The ARIA label for the home page in the breadcrumbs',
-        })}
-        className={clsx('breadcrumbs__link', styles.breadcrumbsItemLink)}
-        href={homeHref}>
-        <IconHome className={styles.breadcrumbHomeIcon} />
-      </Link>
-    </li>
-  );
-}
 export default function DocBreadcrumbs() {
   const breadcrumbs = useSidebarBreadcrumbs();
   const homePageRoute = useHomePageRoute();

package/lib/theme/DocBreadcrumbs/styles.module.css

@@ -9,11 +9,3 @@
   --ifm-breadcrumb-size-multiplier: 0.8;
   margin-bottom: 0.8rem;
 }
-
-.breadcrumbHomeIcon {
-  position: relative;
-  top: 1px;
-  vertical-align: top;
-  height: 1.1rem;
-  width: 1.1rem;
-}

package/lib/theme/DocPage/Layout/Sidebar/ExpandButton/styles.module.css

@@ -7,10 +7,11 @@
 
 @media (min-width: 997px) {
   .expandButton {
-    position: sticky;
+    position: absolute;
     top: 0;
+    right: 0;
+    width: 100%;
     height: 100%;
-    max-height: 100vh;
     display: flex;
     align-items: center;
     justify-content: center;

package/lib/theme/DocPage/Layout/Sidebar/index.js

@@ -52,15 +52,20 @@ export default function DocPageLayoutSidebar({
         }
       }}>
       <ResetOnSidebarChange>
-        <DocSidebar
-          sidebar={sidebar}
-          path={pathname}
-          onCollapse={toggleSidebar}
-          isHidden={hiddenSidebar}
-        />
+        <div
+          className={clsx(
+            styles.sidebarViewport,
+            hiddenSidebar && styles.sidebarViewportHidden,
+          )}>
+          <DocSidebar
+            sidebar={sidebar}
+            path={pathname}
+            onCollapse={toggleSidebar}
+            isHidden={hiddenSidebar}
+          />
+          {hiddenSidebar && <ExpandButton toggleSidebar={toggleSidebar} />}
+        </div>
       </ResetOnSidebarChange>
-
-      {hiddenSidebar && <ExpandButton toggleSidebar={toggleSidebar} />}
     </aside>
   );
 }

package/lib/theme/DocPage/Layout/Sidebar/styles.module.css

@@ -29,4 +29,11 @@
     width: var(--doc-sidebar-hidden-width);
     cursor: pointer;
   }
+
+  .sidebarViewport {
+    top: 0;
+    position: sticky;
+    height: 100%;
+    max-height: 100vh;
+  }
 }

package/lib/theme/DocPage/Layout/styles.module.css

@@ -12,4 +12,5 @@
 
 .docsWrapper {
   display: flex;
+  flex: 1 0 auto;
 }

package/lib/theme/DocSidebar/Desktop/CollapseButton/styles.module.css

@@ -43,4 +43,5 @@
 
 .collapseSidebarButton {
   display: none;
+  margin: 0;
 }

package/lib/theme/DocSidebar/Desktop/Content/index.js

@@ -11,6 +11,7 @@ import {
   useAnnouncementBar,
   useScrollPosition,
 } from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import DocSidebarItems from '@theme/DocSidebarItems';
 import styles from './styles.module.css';
 function useShowAnnouncementBar() {
@@ -30,6 +31,11 @@ export default function DocSidebarDesktopContent({path, sidebar, className}) {
   const showAnnouncementBar = useShowAnnouncementBar();
   return (
     <nav
+      aria-label={translate({
+        id: 'theme.docs.sidebar.navAriaLabel',
+        message: 'Docs sidebar',
+        description: 'The ARIA label for the sidebar navigation',
+      })}
       className={clsx(
         'menu thin-scrollbar',
         styles.menu,

package/lib/theme/DocSidebar/Desktop/styles.module.css

@@ -9,13 +9,9 @@
   .sidebar {
     display: flex;
     flex-direction: column;
-    max-height: 100vh;
     height: 100%;
-    position: sticky;
-    top: 0;
     padding-top: var(--ifm-navbar-height);
     width: var(--doc-sidebar-width);
-    transition: opacity 50ms ease;
   }
 
   .sidebarWithHideableNavbar {
@@ -24,8 +20,6 @@
 
   .sidebarHidden {
     opacity: 0;
-    height: 0;
-    overflow: hidden;
     visibility: hidden;
   }
 

package/lib/theme/Heading/index.js

@@ -8,6 +8,7 @@ import React from 'react';
 import clsx from 'clsx';
 import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
+import Link from '@docusaurus/Link';
 import styles from './styles.module.css';
 export default function Heading({as: As, id, ...props}) {
   const {
@@ -17,6 +18,16 @@ export default function Heading({as: As, id, ...props}) {
   if (As === 'h1' || !id) {
     return <As {...props} id={undefined} />;
   }
+  const anchorTitle = translate(
+    {
+      id: 'theme.common.headingLinkTitle',
+      message: 'Direct link to {heading}',
+      description: 'Title for link to heading',
+    },
+    {
+      heading: typeof props.children === 'string' ? props.children : id,
+    },
+  );
   return (
     <As
       {...props}
@@ -25,19 +36,17 @@ export default function Heading({as: As, id, ...props}) {
         hideOnScroll
           ? styles.anchorWithHideOnScrollNavbar
           : styles.anchorWithStickyNavbar,
+        props.className,
       )}
       id={id}>
       {props.children}
-      <a
+      <Link
         className="hash-link"
-        href={`#${id}`}
-        title={translate({
-          id: 'theme.common.headingLinkTitle',
-          message: 'Direct link to heading',
-          description: 'Title for link to heading',
-        })}>
+        to={`#${id}`}
+        aria-label={anchorTitle}
+        title={anchorTitle}>
         &#8203;
-      </a>
+      </Link>
     </As>
   );
 }

package/lib/theme/Layout/Provider/index.js

@@ -8,7 +8,6 @@ import React from 'react';
 import {composeProviders} from '@docusaurus/theme-common';
 import {
   ColorModeProvider,
-  TabGroupChoiceProvider,
   AnnouncementBarProvider,
   DocsPreferredVersionContextProvider,
   ScrollControllerProvider,
@@ -18,7 +17,6 @@ import {
 const Provider = composeProviders([
   ColorModeProvider,
   AnnouncementBarProvider,
-  TabGroupChoiceProvider,
   ScrollControllerProvider,
   DocsPreferredVersionContextProvider,
   PluginHtmlClassNameProvider,

package/lib/theme/Layout/index.js

@@ -7,7 +7,11 @@
 import React from 'react';
 import clsx from 'clsx';
 import ErrorBoundary from '@docusaurus/ErrorBoundary';
-import {PageMetadata, ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  PageMetadata,
+  SkipToContentFallbackId,
+  ThemeClassNames,
+} from '@docusaurus/theme-common';
 import {useKeyboardNavigation} from '@docusaurus/theme-common/internal';
 import SkipToContent from '@theme/SkipToContent';
 import AnnouncementBar from '@theme/AnnouncementBar';
@@ -37,6 +41,7 @@ export default function Layout(props) {
       <Navbar />
 
       <div
+        id={SkipToContentFallbackId}
         className={clsx(
           ThemeClassNames.wrapper.main,
           styles.mainWrapper,

package/lib/theme/Layout/styles.module.css

@@ -12,6 +12,8 @@ body {
 
 .mainWrapper {
   flex: 1 0 auto;
+  display: flex;
+  flex-direction: column;
 }
 
 /* Docusaurus-specific utility class */

package/lib/theme/MDXComponents/Code.js

@@ -9,15 +9,35 @@ import CodeBlock from '@theme/CodeBlock';
 export default function MDXCode(props) {
   const inlineElements = [
     'a',
+    'abbr',
     'b',
-    'big',
+    'br',
+    'button',
+    'cite',
+    'code',
+    'del',
+    'dfn',
+    'em',
     'i',
+    'img',
+    'input',
+    'ins',
+    'kbd',
+    'label',
+    'object',
+    'output',
+    'q',
+    'ruby',
+    's',
+    'small',
     'span',
-    'em',
     'strong',
-    'sup',
     'sub',
-    'small',
+    'sup',
+    'time',
+    'u',
+    'var',
+    'wbr',
   ];
   const shouldBeInline = React.Children.toArray(props.children).every(
     (el) =>

package/lib/theme/MDXComponents/index.js

@@ -14,6 +14,7 @@ import MDXHeading from '@theme/MDXComponents/Heading';
 import MDXUl from '@theme/MDXComponents/Ul';
 import MDXImg from '@theme/MDXComponents/Img';
 import Admonition from '@theme/Admonition';
+import Mermaid from '@theme/Mermaid';
 const MDXComponents = {
   head: MDXHead,
   code: MDXCode,
@@ -29,5 +30,6 @@ const MDXComponents = {
   h5: (props) => <MDXHeading as="h5" {...props} />,
   h6: (props) => <MDXHeading as="h6" {...props} />,
   admonition: Admonition,
+  mermaid: Mermaid,
 };
 export default MDXComponents;

package/lib/theme/Mermaid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export { default } from '@docusaurus/Noop';

package/lib/theme/Mermaid.js

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+// This component is meant to be implemented by a Mermaid renderer theme
+// It is notable created to be overridden by docusaurus-theme-mermaid
+// By default, the classic theme does not provide any Mermaid implementation
+// Yet we declare it there so that we can register it in MDX
+// TODO later the mermaid theme should be able to register its MDX component
+// see https://github.com/facebook/docusaurus/pull/7490#issuecomment-1279117288
+export {default} from '@docusaurus/Noop';

package/lib/theme/Navbar/Layout/index.js

@@ -11,6 +11,7 @@ import {
   useHideableNavbar,
   useNavbarMobileSidebar,
 } from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import NavbarMobileSidebar from '@theme/Navbar/MobileSidebar';
 import styles from './styles.module.css';
 function NavbarBackdrop(props) {
@@ -31,6 +32,11 @@ export default function NavbarLayout({children}) {
   return (
     <nav
       ref={navbarRef}
+      aria-label={translate({
+        id: 'theme.NavBar.navAriaLabel',
+        message: 'Main',
+        description: 'The ARIA label for the main navigation',
+      })}
       className={clsx(
         'navbar',
         'navbar--fixed-top',

package/lib/theme/Navbar/MobileSidebar/Header/index.js

@@ -6,6 +6,7 @@
  */
 import React from 'react';
 import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import NavbarColorModeToggle from '@theme/Navbar/ColorModeToggle';
 import IconClose from '@theme/Icon/Close';
 import NavbarLogo from '@theme/Navbar/Logo';
@@ -14,6 +15,11 @@ function CloseButton() {
   return (
     <button
       type="button"
+      aria-label={translate({
+        id: 'theme.docs.sidebar.closeSidebarButtonAriaLabel',
+        message: 'Close navigation bar',
+        description: 'The ARIA label for close button of mobile sidebar',
+      })}
       className="clean-btn navbar-sidebar__close"
       onClick={() => mobileSidebar.toggle()}>
       <IconClose color="var(--ifm-color-emphasis-600)" />

package/lib/theme/Navbar/MobileSidebar/Toggle/index.js

@@ -6,17 +6,22 @@
  */
 import React from 'react';
 import {useNavbarMobileSidebar} from '@docusaurus/theme-common/internal';
+import {translate} from '@docusaurus/Translate';
 import IconMenu from '@theme/Icon/Menu';
 export default function MobileSidebarToggle() {
-  const mobileSidebar = useNavbarMobileSidebar();
+  const {toggle, shown} = useNavbarMobileSidebar();
   return (
     <button
-      onClick={mobileSidebar.toggle}
-      onKeyDown={mobileSidebar.toggle}
-      aria-label="Navigation bar toggle"
+      onClick={toggle}
+      aria-label={translate({
+        id: 'theme.docs.sidebar.toggleSidebarButtonAriaLabel',
+        message: 'Toggle navigation bar',
+        description:
+          'The ARIA label for hamburger menu button of mobile navigation',
+      })}
+      aria-expanded={shown}
       className="navbar__toggle clean-btn"
-      type="button"
-      tabIndex={0}>
+      type="button">
       <IconMenu />
     </button>
   );

package/lib/theme/NavbarItem/DocsVersionDropdownNavbarItem.js

@@ -12,6 +12,7 @@ import {
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 import {useDocsVersionCandidates} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
+import {useLocation} from '@docusaurus/router';
 import DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 const getVersionMainDoc = (version) =>
@@ -24,6 +25,7 @@ export default function DocsVersionDropdownNavbarItem({
   dropdownItemsAfter,
   ...props
 }) {
+  const {search, hash} = useLocation();
   const activeDocContext = useActiveDocContext(docsPluginId);
   const versions = useVersions(docsPluginId);
   const {savePreferredVersionName} = useDocsPreferredVersion(docsPluginId);
@@ -35,7 +37,8 @@ export default function DocsVersionDropdownNavbarItem({
       getVersionMainDoc(version);
     return {
       label: version.label,
-      to: versionDoc.path,
+      // preserve ?search#hash suffix on version switches
+      to: `${versionDoc.path}${search}${hash}`,
       isActive: () => version === activeDocContext.activeVersion,
       onClick: () => savePreferredVersionName(version.name),
     };

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

@@ -8,6 +8,7 @@ import React from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import {useAlternatePageUtils} from '@docusaurus/theme-common/internal';
 import {translate} from '@docusaurus/Translate';
+import {useLocation} from '@docusaurus/router';
 import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
 import IconLanguage from '@theme/Icon/Language';
 import styles from './styles.module.css';
@@ -21,11 +22,14 @@ export default function LocaleDropdownNavbarItem({
     i18n: {currentLocale, locales, localeConfigs},
   } = useDocusaurusContext();
   const alternatePageUtils = useAlternatePageUtils();
+  const {search, hash} = useLocation();
   const localeItems = locales.map((locale) => {
-    const to = `pathname://${alternatePageUtils.createUrl({
+    const baseTo = `pathname://${alternatePageUtils.createUrl({
       locale,
       fullyQualified: false,
     })}`;
+    // preserve ?search#hash suffix on locale switches
+    const to = `${baseTo}${search}${hash}`;
     return {
       label: localeConfigs[locale].label,
       lang: localeConfigs[locale].htmlLang,