@docusaurus/theme-classic 2.0.0-beta.1ab8aa0af → 2.0.0-beta.2

package/lib-next/theme/DocItem/styles.module.css

@@ -5,24 +5,22 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docTitle {
-  font-size: 3rem;
-  margin-bottom: calc(var(--ifm-leading-desktop) * var(--ifm-leading));
+.docItemContainer header + * {
+  margin-top: 0;
 }
 
-.docItemContainer {
-  margin: 0 auto;
-  padding: 0 0.5rem;
+.lastUpdated {
+  margin-top: 0.2rem;
+  font-style: italic;
+  font-size: smaller;
 }
 
 @media only screen and (min-width: 997px) {
   .docItemCol {
     max-width: 75% !important;
   }
-}
 
-@media only screen and (max-width: 996px) {
-  .docItemContainer {
-    padding: 0 0.3rem;
+  .lastUpdated {
+    text-align: right;
   }
 }

package/lib-next/theme/DocPage/index.js

@@ -19,11 +19,37 @@ import clsx from 'clsx';
 import styles from './styles.module.css';
 import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
 
+function getSidebar({versionMetadata, currentDocRoute}) {
+  function addTrailingSlash(str) {
+    return str.endsWith('/') ? str : `${str}/`;
+  }
+
+  function removeTrailingSlash(str) {
+    return str.endsWith('/') ? str.slice(0, -1) : str;
+  }
+
+  const {permalinkToSidebar, docsSidebars} = versionMetadata; // With/without trailingSlash, we should always be able to get the appropriate sidebar
+  // note: docs plugin permalinks currently never have trailing slashes
+  // trailingSlash is handled globally at the framework level, not plugin level
+
+  const sidebarName =
+    permalinkToSidebar[currentDocRoute.path] ||
+    permalinkToSidebar[addTrailingSlash(currentDocRoute.path)] ||
+    permalinkToSidebar[removeTrailingSlash(currentDocRoute.path)];
+  const sidebar = docsSidebars[sidebarName];
+  return {
+    sidebar,
+    sidebarName,
+  };
+}
+
 function DocPageContent({currentDocRoute, versionMetadata, children}) {
   const {siteConfig, isClient} = useDocusaurusContext();
-  const {pluginId, permalinkToSidebar, docsSidebars, version} = versionMetadata;
-  const sidebarName = permalinkToSidebar[currentDocRoute.path];
-  const sidebar = docsSidebars[sidebarName];
+  const {pluginId, version} = versionMetadata;
+  const {sidebarName, sidebar} = getSidebar({
+    versionMetadata,
+    currentDocRoute,
+  });
   const [hiddenSidebarContainer, setHiddenSidebarContainer] = useState(false);
   const [hiddenSidebar, setHiddenSidebar] = useState(false);
   const toggleSidebar = useCallback(() => {
@@ -44,7 +70,7 @@ function DocPageContent({currentDocRoute, versionMetadata, children}) {
       }}>
       <div className={styles.docPage}>
         {sidebar && (
-          <div
+          <aside
             className={clsx(styles.docSidebarContainer, {
               [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
             })}
@@ -58,8 +84,7 @@ function DocPageContent({currentDocRoute, versionMetadata, children}) {
               if (hiddenSidebarContainer) {
                 setHiddenSidebar(true);
               }
-            }}
-            role="complementary">
+            }}>
             <DocSidebar
               key={
                 // Reset sidebar state on sidebar changes
@@ -97,7 +122,7 @@ function DocPageContent({currentDocRoute, versionMetadata, children}) {
                 <IconArrow className={styles.expandSidebarButtonIcon} />
               </div>
             )}
-          </div>
+          </aside>
         )}
         <main
           className={clsx(styles.docMainContainer, {
@@ -106,7 +131,7 @@ function DocPageContent({currentDocRoute, versionMetadata, children}) {
           })}>
           <div
             className={clsx(
-              'container padding-vert--lg',
+              'container padding-top--md padding-bottom--lg',
               styles.docItemWrapper,
               {
                 [styles.docItemWrapperEnhanced]: hiddenSidebarContainer,
@@ -138,7 +163,9 @@ function DocPage(props) {
     <DocPageContent
       currentDocRoute={currentDocRoute}
       versionMetadata={versionMetadata}>
-      {renderRoutes(docRoutes)}
+      {renderRoutes(docRoutes, {
+        versionMetadata,
+      })}
     </DocPageContent>
   );
 }

package/lib-next/theme/DocPage/styles.module.css

@@ -7,6 +7,7 @@
 
 :root {
   --doc-sidebar-width: 300px;
+  --doc-sidebar-hidden-width: 30px;
 }
 
 :global(.docs-wrapper) {
@@ -26,7 +27,7 @@
   }
 
   .docMainContainerEnhanced {
-    max-width: none;
+    max-width: calc(100% - var(--doc-sidebar-hidden-width));
   }
 
   .docSidebarContainer {
@@ -39,7 +40,7 @@
   }
 
   .docSidebarContainerHidden {
-    width: 30px;
+    width: var(--doc-sidebar-hidden-width);
     cursor: pointer;
   }
 
@@ -72,27 +73,14 @@
   }
 
   .docItemWrapperEnhanced {
-    max-width: calc(var(--ifm-container-width) + var(--doc-sidebar-width)) !important;
+    max-width: calc(
+      var(--ifm-container-width) + var(--doc-sidebar-width)
+    ) !important;
   }
 }
 
 @media (max-width: 996px) {
   .docSidebarContainer {
-    margin-top: 0;
-  }
-}
-
-@media (min-width: 997px) and (max-width: 1320px) {
-  .docItemWrapper {
-    max-width: calc(
-      var(--ifm-container-width) - var(--doc-sidebar-width) -
-        var(--ifm-spacing-horizontal) * 2
-    );
-  }
-
-  .docItemWrapperEnhanced {
-    max-width: calc(
-      var(--ifm-container-width) - var(--ifm-spacing-horizontal) * 2
-    );
+    display: none;
   }
 }

package/lib-next/theme/DocPaginator/index.js

@@ -12,7 +12,7 @@ function DocPaginator(props) {
   const {metadata} = props;
   return (
     <nav
-      className="pagination-nav"
+      className="pagination-nav docusaurus-mt-lg"
       aria-label={translate({
         id: 'theme.docs.paginator.navAriaLabel',
         message: 'Docs pages navigation',

package/lib-next/theme/DocSidebar/index.js

@@ -6,8 +6,12 @@
  */
 import React, {useState, useCallback, useEffect, useRef, memo} from 'react';
 import clsx from 'clsx';
-import {useThemeConfig, isSamePath} from '@docusaurus/theme-common';
-import useUserPreferencesContext from '@theme/hooks/useUserPreferencesContext';
+import {
+  useThemeConfig,
+  isSamePath,
+  usePrevious,
+  useAnnouncementBar,
+} from '@docusaurus/theme-common';
 import useLockBodyScroll from '@theme/hooks/useLockBodyScroll';
 import useWindowSize, {windowSizes} from '@theme/hooks/useWindowSize';
 import useScrollPosition from '@theme/hooks/useScrollPosition';
@@ -16,18 +20,11 @@ import isInternalUrl from '@docusaurus/isInternalUrl';
 import Logo from '@theme/Logo';
 import IconArrow from '@theme/IconArrow';
 import IconMenu from '@theme/IconMenu';
+import IconExternalLink from '@theme/IconExternalLink';
 import {translate} from '@docusaurus/Translate';
 import styles from './styles.module.css';
 const MOBILE_TOGGLE_SIZE = 24;
 
-function usePrevious(value) {
-  const ref = useRef(value);
-  useEffect(() => {
-    ref.current = value;
-  }, [value]);
-  return ref.current;
-}
-
 const isActiveSidebarItem = (item, activePath) => {
   if (item.type === 'link') {
     return isSamePath(item.href, activePath);
@@ -170,7 +167,6 @@ function DocSidebarItemLink({
       <Link
         className={clsx('menu__link', {
           'menu__link--active': isActive,
-          [styles.menuLinkExternal]: !isInternalUrl(href),
         })}
         to={href}
         {...(isInternalUrl(href) && {
@@ -179,19 +175,24 @@ function DocSidebarItemLink({
           onClick: onItemClick,
         })}
         {...props}>
-        {label}
+        {isInternalUrl(href) ? (
+          label
+        ) : (
+          <span>
+            {label}
+            <IconExternalLink />
+          </span>
+        )}
       </Link>
     </li>
   );
 }
 
 function useShowAnnouncementBar() {
-  const {isAnnouncementBarClosed} = useUserPreferencesContext();
-  const [showAnnouncementBar, setShowAnnouncementBar] = useState(
-    !isAnnouncementBarClosed,
-  );
+  const {isClosed} = useAnnouncementBar();
+  const [showAnnouncementBar, setShowAnnouncementBar] = useState(!isClosed);
   useScrollPosition(({scrollY}) => {
-    if (!isAnnouncementBarClosed) {
+    if (!isClosed) {
       setShowAnnouncementBar(scrollY === 0);
     }
   });
@@ -298,7 +299,7 @@ function DocSidebar({
     navbar: {hideOnScroll},
     hideableSidebar,
   } = useThemeConfig();
-  const {isAnnouncementBarClosed} = useUserPreferencesContext();
+  const {isClosed: isAnnouncementBarClosed} = useAnnouncementBar();
   const {
     showResponsiveSidebar,
     closeResponsiveSidebar,
@@ -311,7 +312,7 @@ function DocSidebar({
         [styles.sidebarHidden]: isHidden,
       })}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
-      <div
+      <nav
         className={clsx(
           'menu',
           'menu--responsive',
@@ -322,11 +323,17 @@ function DocSidebar({
             [styles.menuWithAnnouncementBar]:
               !isAnnouncementBarClosed && showAnnouncementBar,
           },
-        )}>
+        )}
+        aria-label={translate({
+          id: 'theme.docs.sidebar.navAriaLabel',
+          message: 'Sidebar navigation',
+          description: 'The ARIA label for documentation menu',
+        })}>
         <ResponsiveSidebarButton
           responsiveSidebarOpened={showResponsiveSidebar}
           onClick={toggleResponsiveSidebar}
         />
+
         <ul className="menu__list">
           <DocSidebarItems
             items={sidebar}
@@ -335,7 +342,7 @@ function DocSidebar({
             activePath={path}
           />
         </ul>
-      </div>
+      </nav>
       {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
     </div>
   );

package/lib-next/theme/DocSidebar/styles.module.css

@@ -122,17 +122,3 @@
 :global(.menu__list-item--collapsed) :global(.menu__list) {
   height: 0 !important;
 }
-
-.menuLinkExternal {
-  align-items: center;
-}
-.menuLinkExternal:after {
-  content: '';
-  height: 1.15rem;
-  width: 1.15rem;
-  min-width: 1.15rem;
-  margin: 0 0 0 3%;
-  background: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='16' height='16' viewBox='0 0 24 24'%3E%3Cpath fill='rgba(0,0,0,0.5)' d='M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z'/%3E%3C/svg%3E")
-    no-repeat;
-  filter: var(--ifm-menu-link-sublist-icon-filter);
-}

package/lib-next/theme/DocVersionBanner/index.js

@@ -0,0 +1,127 @@
+/**
+ * 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 useDocusaurusContext from '@docusaurus/useDocusaurusContext';
+import Link from '@docusaurus/Link';
+import Translate from '@docusaurus/Translate';
+import {useActivePlugin, useDocVersionSuggestions} from '@theme/hooks/useDocs';
+import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+
+function UnreleasedVersionLabel({siteTitle, versionMetadata}) {
+  return (
+    <Translate
+      id="theme.docs.versions.unreleasedVersionLabel"
+      description="The label used to tell the user that he's browsing an unreleased doc version"
+      values={{
+        siteTitle,
+        versionLabel: <b>{versionMetadata.label}</b>,
+      }}>
+      {
+        'This is unreleased documentation for {siteTitle} {versionLabel} version.'
+      }
+    </Translate>
+  );
+}
+
+function UnmaintainedVersionLabel({siteTitle, versionMetadata}) {
+  return (
+    <Translate
+      id="theme.docs.versions.unmaintainedVersionLabel"
+      description="The label used to tell the user that he's browsing an unmaintained doc version"
+      values={{
+        siteTitle,
+        versionLabel: <b>{versionMetadata.label}</b>,
+      }}>
+      {
+        'This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.'
+      }
+    </Translate>
+  );
+}
+
+const BannerLabelComponents = {
+  unreleased: UnreleasedVersionLabel,
+  unmaintained: UnmaintainedVersionLabel,
+};
+
+function BannerLabel(props) {
+  const BannerLabelComponent =
+    BannerLabelComponents[props.versionMetadata.banner];
+  return <BannerLabelComponent {...props} />;
+}
+
+function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
+  return (
+    <Translate
+      id="theme.docs.versions.latestVersionSuggestionLabel"
+      description="The label used to tell the user to check the latest version"
+      values={{
+        versionLabel,
+        latestVersionLink: (
+          <b>
+            <Link to={to} onClick={onClick}>
+              <Translate
+                id="theme.docs.versions.latestVersionLinkLabel"
+                description="The label used for the latest version suggestion link label">
+                latest version
+              </Translate>
+            </Link>
+          </b>
+        ),
+      }}>
+      {
+        'For up-to-date documentation, see the {latestVersionLink} ({versionLabel}).'
+      }
+    </Translate>
+  );
+}
+
+function DocVersionBannerEnabled({versionMetadata}) {
+  const {
+    siteConfig: {title: siteTitle},
+  } = useDocusaurusContext();
+  const {pluginId} = useActivePlugin({
+    failfast: true,
+  });
+
+  const getVersionMainDoc = (version) =>
+    version.docs.find((doc) => doc.id === version.mainDocId);
+
+  const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
+  const {
+    latestDocSuggestion,
+    latestVersionSuggestion,
+  } = useDocVersionSuggestions(pluginId); // try to link to same doc in latest version (not always possible)
+  // fallback to main doc of latest version
+
+  const latestVersionSuggestedDoc =
+    latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
+  return (
+    <div className="alert alert--warning margin-bottom--md" role="alert">
+      <div>
+        <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
+      </div>
+      <div className="margin-top--md">
+        <LatestVersionSuggestionLabel
+          versionLabel={latestVersionSuggestion.label}
+          to={latestVersionSuggestedDoc.path}
+          onClick={() => savePreferredVersionName(latestVersionSuggestion.name)}
+        />
+      </div>
+    </div>
+  );
+}
+
+function DocVersionBanner({versionMetadata}) {
+  if (versionMetadata.banner === 'none') {
+    return <></>;
+  } else {
+    return <DocVersionBannerEnabled versionMetadata={versionMetadata} />;
+  }
+}
+
+export default DocVersionBanner;

package/lib-next/theme/DocVersionSuggestions/index.js

@@ -22,7 +22,7 @@ function UnreleasedVersionLabel({siteTitle, versionLabel}) {
       description="The label used to tell the user that he's browsing an unreleased doc version"
       values={{
         siteTitle,
-        versionLabel: <strong>{versionLabel}</strong>,
+        versionLabel: <b>{versionLabel}</b>,
       }}>
       {
         'This is unreleased documentation for {siteTitle} {versionLabel} version.'
@@ -38,7 +38,7 @@ function UnmaintainedVersionLabel({siteTitle, versionLabel}) {
       description="The label used to tell the user that he's browsing an unmaintained doc version"
       values={{
         siteTitle,
-        versionLabel: <strong>{versionLabel}</strong>,
+        versionLabel: <b>{versionLabel}</b>,
       }}>
       {
         'This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.'
@@ -55,7 +55,7 @@ function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
       values={{
         versionLabel,
         latestVersionLink: (
-          <strong>
+          <b>
             <Link to={to} onClick={onClick}>
               <Translate
                 id="theme.docs.versions.latestVersionLinkLabel"
@@ -63,7 +63,7 @@ function LatestVersionSuggestionLabel({versionLabel, to, onClick}) {
                 latest version
               </Translate>
             </Link>
-          </strong>
+          </b>
         ),
       }}>
       {

package/lib-next/theme/Heading/index.js

@@ -12,8 +12,20 @@ import {translate} from '@docusaurus/Translate';
 import {useThemeConfig} from '@docusaurus/theme-common';
 import './styles.css';
 import styles from './styles.module.css';
+export const MainHeading = function MainHeading({...props}) {
+  return (
+    <header>
+      <h1
+        {...props}
+        id={undefined} // h1 headings do not need an id because they don't appear in the TOC
+        className={styles.h1Heading}>
+        {props.children}
+      </h1>
+    </header>
+  );
+};
 
-const Heading = (Tag) =>
+const createAnchorHeading = (Tag) =>
   function TargetComponent({id, ...props}) {
     const {
       navbar: {hideOnScroll},
@@ -48,4 +60,8 @@ const Heading = (Tag) =>
     );
   };
 
+const Heading = (headingType) => {
+  return headingType === 'h1' ? MainHeading : createAnchorHeading(headingType);
+};
+
 export default Heading;

package/lib-next/theme/Heading/styles.module.css

@@ -8,3 +8,8 @@
 .enhancedAnchor {
   top: calc(var(--ifm-navbar-height) * -1 - 0.5rem);
 }
+
+.h1Heading {
+  font-size: 3rem;
+  margin-bottom: calc(var(--ifm-leading-desktop) * var(--ifm-leading));
+}

package/lib-next/theme/IconArrow/index.js

@@ -8,7 +8,7 @@ import React from 'react';
 
 const IconArrow = (props) => {
   return (
-    <svg width="20" height="20" role="img" {...props}>
+    <svg width="20" height="20" aria-hidden="true" {...props}>
       <g fill="#7a7a7a">
         <path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0" />
         <path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0" />

package/lib-next/theme/IconEdit/index.js

@@ -12,13 +12,11 @@ const IconEdit = ({className, ...restProps}) => {
   return (
     <svg
       fill="currentColor"
-      height="1.2em"
-      width="1.2em"
-      preserveAspectRatio="xMidYMid meet"
-      role="img"
+      height="20"
+      width="20"
       viewBox="0 0 40 40"
       className={clsx(styles.iconEdit, className)}
-      aria-label="Edit page"
+      aria-hidden="true"
       {...restProps}>
       <g>
         <path d="m34.5 11.7l-3 3.1-6.3-6.3 3.1-3q0.5-0.5 1.2-0.5t1.1 0.5l3.9 3.9q0.5 0.4 0.5 1.1t-0.5 1.2z m-29.5 17.1l18.4-18.5 6.3 6.3-18.4 18.4h-6.3v-6.2z" />

package/lib-next/theme/IconExternalLink/index.js

@@ -0,0 +1,26 @@
+/**
+ * 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 styles from './styles.module.css';
+
+const IconExternalLink = ({width = 13.5, height = 13.5}) => {
+  return (
+    <svg
+      width={width}
+      height={height}
+      aria-hidden="true"
+      viewBox="0 0 24 24"
+      className={styles.iconExternalLink}>
+      <path
+        fill="currentColor"
+        d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"
+      />
+    </svg>
+  );
+};
+
+export default IconExternalLink;

package/{lib/theme/NavbarItem → lib-next/theme/IconExternalLink}/styles.module.css

@@ -5,9 +5,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-@media (max-width: 996px) {
-  .searchWrapper {
-    position: absolute;
-    right: var(--ifm-navbar-padding-horizontal);
-  }
+.iconExternalLink {
+  margin-left: 0.3rem;
+  position: relative;
+  top: 1px;
 }

package/lib-next/theme/IconLanguage/index.js

@@ -9,10 +9,10 @@ import React from 'react';
 const IconLanguage = ({width = 20, height = 20, ...props}) => {
   return (
     <svg
-      xmlns="http://www.w3.org/2000/svg"
       viewBox="0 0 20 20"
       width={width}
       height={height}
+      aria-hidden="true"
       {...props}>
       <path
         fill="currentColor"

package/lib-next/theme/IconMenu/index.js

@@ -9,15 +9,12 @@ import React from 'react';
 const IconMenu = ({width = 30, height = 30, className, ...restProps}) => {
   return (
     <svg
-      aria-label="Menu"
       className={className}
       width={width}
       height={height}
       viewBox="0 0 30 30"
-      role="img"
-      focusable="false"
+      aria-hidden="true"
       {...restProps}>
-      <title>Menu</title>
       <path
         stroke="currentColor"
         strokeLinecap="round"