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

package/src/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/src/theme/DocPage/index.tsx

@@ -31,15 +31,36 @@ type DocPageContentProps = {
   readonly children: ReactNode;
 };
 
+function getSidebar({versionMetadata, currentDocRoute}) {
+  function addTrailingSlash(str: string): string {
+    return str.endsWith('/') ? str : `${str}/`;
+  }
+  function removeTrailingSlash(str: string): string {
+    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,
 }: DocPageContentProps): JSX.Element {
   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);
@@ -62,7 +83,7 @@ function DocPageContent({
       }}>
       <div className={styles.docPage}>
         {sidebar && (
-          <div
+          <aside
             className={clsx(styles.docSidebarContainer, {
               [styles.docSidebarContainerHidden]: hiddenSidebarContainer,
             })}
@@ -76,8 +97,7 @@ function DocPageContent({
               if (hiddenSidebarContainer) {
                 setHiddenSidebar(true);
               }
-            }}
-            role="complementary">
+            }}>
             <DocSidebar
               key={
                 // Reset sidebar state on sidebar changes
@@ -115,7 +135,7 @@ function DocPageContent({
                 <IconArrow className={styles.expandSidebarButtonIcon} />
               </div>
             )}
-          </div>
+          </aside>
         )}
         <main
           className={clsx(styles.docMainContainer, {
@@ -124,7 +144,7 @@ function DocPageContent({
           })}>
           <div
             className={clsx(
-              'container padding-vert--lg',
+              'container padding-top--md padding-bottom--lg',
               styles.docItemWrapper,
               {
                 [styles.docItemWrapperEnhanced]: hiddenSidebarContainer,
@@ -154,7 +174,7 @@ function DocPage(props: Props): JSX.Element {
     <DocPageContent
       currentDocRoute={currentDocRoute}
       versionMetadata={versionMetadata}>
-      {renderRoutes(docRoutes)}
+      {renderRoutes(docRoutes, {versionMetadata})}
     </DocPageContent>
   );
 }

package/src/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/src/theme/DocPaginator/index.tsx

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

package/src/theme/DocSidebar/index.tsx

@@ -7,8 +7,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';
@@ -18,20 +22,13 @@ import type {Props} from '@theme/DocSidebar';
 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);
@@ -179,7 +176,6 @@ function DocSidebarItemLink({
       <Link
         className={clsx('menu__link', {
           'menu__link--active': isActive,
-          [styles.menuLinkExternal]: !isInternalUrl(href),
         })}
         to={href}
         {...(isInternalUrl(href) && {
@@ -188,19 +184,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);
     }
   });
@@ -311,7 +312,7 @@ function DocSidebar({
     navbar: {hideOnScroll},
     hideableSidebar,
   } = useThemeConfig();
-  const {isAnnouncementBarClosed} = useUserPreferencesContext();
+  const {isClosed: isAnnouncementBarClosed} = useAnnouncementBar();
 
   const {
     showResponsiveSidebar,
@@ -326,7 +327,7 @@ function DocSidebar({
         [styles.sidebarHidden]: isHidden,
       })}>
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
-      <div
+      <nav
         className={clsx(
           'menu',
           'menu--responsive',
@@ -337,11 +338,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}
@@ -350,7 +357,7 @@ function DocSidebar({
             activePath={path}
           />
         </ul>
-      </div>
+      </nav>
       {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
     </div>
   );

package/src/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/src/theme/{DocVersionSuggestions → DocVersionBanner}/index.tsx

@@ -5,31 +5,31 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {ComponentType} from 'react';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
-import {
-  useActivePlugin,
-  useActiveVersion,
-  useDocVersionSuggestions,
-} from '@theme/hooks/useDocs';
+import {useActivePlugin, useDocVersionSuggestions} from '@theme/hooks/useDocs';
 import {useDocsPreferredVersion} from '@docusaurus/theme-common';
 
+import type {Props} from '@theme/DocVersionBanner';
+
+type BannerLabelComponentProps = {
+  siteTitle: string;
+  versionMetadata: Props['versionMetadata'];
+};
+
 function UnreleasedVersionLabel({
   siteTitle,
-  versionLabel,
-}: {
-  siteTitle: string;
-  versionLabel: string;
-}) {
+  versionMetadata,
+}: BannerLabelComponentProps) {
   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: <strong>{versionLabel}</strong>,
+        versionLabel: <b>{versionMetadata.label}</b>,
       }}>
       {
         'This is unreleased documentation for {siteTitle} {versionLabel} version.'
@@ -40,18 +40,15 @@ function UnreleasedVersionLabel({
 
 function UnmaintainedVersionLabel({
   siteTitle,
-  versionLabel,
-}: {
-  siteTitle: string;
-  versionLabel: string;
-}) {
+  versionMetadata,
+}: BannerLabelComponentProps) {
   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: <strong>{versionLabel}</strong>,
+        versionLabel: <b>{versionMetadata.label}</b>,
       }}>
       {
         'This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained.'
@@ -60,6 +57,20 @@ function UnmaintainedVersionLabel({
   );
 }
 
+const BannerLabelComponents: Record<
+  Props['versionMetadata']['banner'],
+  ComponentType<BannerLabelComponentProps>
+> = {
+  unreleased: UnreleasedVersionLabel,
+  unmaintained: UnmaintainedVersionLabel,
+};
+
+function BannerLabel(props: BannerLabelComponentProps) {
+  const BannerLabelComponent =
+    BannerLabelComponents[props.versionMetadata.banner];
+  return <BannerLabelComponent {...props} />;
+}
+
 function LatestVersionSuggestionLabel({
   versionLabel,
   to,
@@ -72,11 +83,11 @@ function LatestVersionSuggestionLabel({
   return (
     <Translate
       id="theme.docs.versions.latestVersionSuggestionLabel"
-      description="The label userd to tell the user that he's browsing an unmaintained doc version"
+      description="The label used to tell the user to check the latest version"
       values={{
         versionLabel,
         latestVersionLink: (
-          <strong>
+          <b>
             <Link to={to} onClick={onClick}>
               <Translate
                 id="theme.docs.versions.latestVersionLinkLabel"
@@ -84,7 +95,7 @@ function LatestVersionSuggestionLabel({
                 latest version
               </Translate>
             </Link>
-          </strong>
+          </b>
         ),
       }}>
       {
@@ -94,28 +105,22 @@ function LatestVersionSuggestionLabel({
   );
 }
 
-const getVersionMainDoc = (version) =>
-  version.docs.find((doc) => doc.id === version.mainDocId);
-
-function DocVersionSuggestions(): JSX.Element {
+function DocVersionBannerEnabled({versionMetadata}: Props): JSX.Element {
   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 activeVersion = useActiveVersion(pluginId);
   const {
     latestDocSuggestion,
     latestVersionSuggestion,
   } = useDocVersionSuggestions(pluginId);
 
-  // No suggestion to be made
-  if (!latestVersionSuggestion) {
-    return <></>;
-  }
-
   // try to link to same doc in latest version (not always possible)
   // fallback to main doc of latest version
   const latestVersionSuggestedDoc =
@@ -124,17 +129,7 @@ function DocVersionSuggestions(): JSX.Element {
   return (
     <div className="alert alert--warning margin-bottom--md" role="alert">
       <div>
-        {activeVersion.name === 'current' ? (
-          <UnreleasedVersionLabel
-            siteTitle={siteTitle}
-            versionLabel={activeVersion.label}
-          />
-        ) : (
-          <UnmaintainedVersionLabel
-            siteTitle={siteTitle}
-            versionLabel={activeVersion.label}
-          />
-        )}
+        <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>
       <div className="margin-top--md">
         <LatestVersionSuggestionLabel
@@ -147,4 +142,12 @@ function DocVersionSuggestions(): JSX.Element {
   );
 }
 
-export default DocVersionSuggestions;
+function DocVersionBanner({versionMetadata}: Props): JSX.Element {
+  if (versionMetadata.banner === 'none') {
+    return <></>;
+  } else {
+    return <DocVersionBannerEnabled versionMetadata={versionMetadata} />;
+  }
+}
+
+export default DocVersionBanner;

package/src/theme/Heading/index.tsx

@@ -16,7 +16,24 @@ import {useThemeConfig} from '@docusaurus/theme-common';
 import './styles.css';
 import styles from './styles.module.css';
 
-const Heading = (Tag: HeadingType): ((props: Props) => JSX.Element) =>
+type HeadingComponent = (props: Props) => JSX.Element;
+
+export const MainHeading: HeadingComponent = 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 createAnchorHeading = (
+  Tag: HeadingType,
+): ((props: Props) => JSX.Element) =>
   function TargetComponent({id, ...props}) {
     const {
       navbar: {hideOnScroll},
@@ -51,4 +68,8 @@ const Heading = (Tag: HeadingType): ((props: Props) => JSX.Element) =>
     );
   };
 
+const Heading = (headingType: HeadingType): ((props: Props) => JSX.Element) => {
+  return headingType === 'h1' ? MainHeading : createAnchorHeading(headingType);
+};
+
 export default Heading;

package/src/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/src/theme/IconArrow/index.tsx

@@ -10,7 +10,7 @@ import type {Props} from '@theme/IconArrow';
 
 const IconArrow = (props: Props): JSX.Element => {
   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/src/theme/IconEdit/index.tsx

@@ -16,13 +16,11 @@ const IconEdit = ({className, ...restProps}: Props): JSX.Element => {
   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/src/theme/IconExternalLink/index.tsx

@@ -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 type {Props} from '@theme/IconExternalLink';
+
+import styles from './styles.module.css';
+
+const IconExternalLink = ({
+  width = 13.5,
+  height = 13.5,
+}: Props): JSX.Element => {
+  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/src/theme/IconExternalLink/styles.module.css

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+
+.iconExternalLink {
+  margin-left: 0.3rem;
+  position: relative;
+  top: 1px;
+}

package/src/theme/IconLanguage/index.tsx

@@ -15,10 +15,10 @@ const IconLanguage = ({
 }: Props): JSX.Element => {
   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/src/theme/IconMenu/index.tsx

@@ -16,15 +16,12 @@ const IconMenu = ({
 }: Props): JSX.Element => {
   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"