@docusaurus/theme-classic 2.0.0-beta.8e9b829d9 → 2.0.0-beta.9

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

@@ -6,19 +6,17 @@
  */
 import React from 'react';
 import clsx from 'clsx';
-import {useActivePlugin, useVersions} from '@theme/hooks/useDocs';
 import useWindowSize from '@theme/hooks/useWindowSize';
 import DocPaginator from '@theme/DocPaginator';
 import DocVersionBanner from '@theme/DocVersionBanner';
 import Seo from '@theme/Seo';
-import LastUpdated from '@theme/LastUpdated';
+import DocItemFooter from '@theme/DocItemFooter';
 import TOC from '@theme/TOC';
 import TOCCollapsible from '@theme/TOCCollapsible';
-import EditThisPage from '@theme/EditThisPage';
 import {MainHeading} from '@theme/Heading';
 import styles from './styles.module.css';
-
-function DocItem(props) {
+import {ThemeClassNames} from '@docusaurus/theme-common';
+export default function DocItem(props) {
   const {content: DocContent, versionMetadata} = props;
   const {metadata, frontMatter} = DocContent;
   const {
@@ -26,23 +24,10 @@ function DocItem(props) {
     keywords,
     hide_title: hideTitle,
     hide_table_of_contents: hideTableOfContents,
+    toc_min_heading_level: tocMinHeadingLevel,
+    toc_max_heading_level: tocMaxHeadingLevel,
   } = frontMatter;
-  const {
-    description,
-    title,
-    editUrl,
-    lastUpdatedAt,
-    formattedLastUpdatedAt,
-    lastUpdatedBy,
-  } = metadata;
-  const {pluginId} = useActivePlugin({
-    failfast: true,
-  });
-  const versions = useVersions(pluginId); // If site is not versioned or only one version is included
-  // we don't show the version badge
-  // See https://github.com/facebook/docusaurus/issues/3362
-
-  const showVersionBadge = versions.length > 1; // We only add a title if:
+  const {description, title} = metadata; // We only add a title if:
   // - user asks to hide it with frontmatter
   // - the markdown content does not already contain a top-level h1 heading
 
@@ -72,8 +57,12 @@ function DocItem(props) {
           <DocVersionBanner versionMetadata={versionMetadata} />
           <div className={styles.docItemContainer}>
             <article>
-              {showVersionBadge && (
-                <span className="badge badge--secondary">
+              {versionMetadata.badge && (
+                <span
+                  className={clsx(
+                    ThemeClassNames.docs.docVersionBadge,
+                    'badge badge--secondary',
+                  )}>
                   Version: {versionMetadata.label}
                 </span>
               )}
@@ -81,11 +70,17 @@ function DocItem(props) {
               {canRenderTOC && (
                 <TOCCollapsible
                   toc={DocContent.toc}
-                  className={styles.tocMobile}
+                  minHeadingLevel={tocMinHeadingLevel}
+                  maxHeadingLevel={tocMaxHeadingLevel}
+                  className={clsx(
+                    ThemeClassNames.docs.docTocMobile,
+                    styles.tocMobile,
+                  )}
                 />
               )}
 
-              <div className="markdown">
+              <div
+                className={clsx(ThemeClassNames.docs.docMarkdown, 'markdown')}>
                 {/*
                 Title can be declared inside md content or declared through frontmatter and added manually
                 To make both cases consistent, the added title is added under the same div.markdown block
@@ -96,23 +91,7 @@ function DocItem(props) {
                 <DocContent />
               </div>
 
-              {(editUrl || lastUpdatedAt || lastUpdatedBy) && (
-                <footer className="row docusaurus-mt-lg">
-                  <div className="col">
-                    {editUrl && <EditThisPage editUrl={editUrl} />}
-                  </div>
-
-                  <div className={clsx('col', styles.lastUpdated)}>
-                    {(lastUpdatedAt || lastUpdatedBy) && (
-                      <LastUpdated
-                        lastUpdatedAt={lastUpdatedAt}
-                        formattedLastUpdatedAt={formattedLastUpdatedAt}
-                        lastUpdatedBy={lastUpdatedBy}
-                      />
-                    )}
-                  </div>
-                </footer>
-              )}
+              <DocItemFooter {...props} />
             </article>
 
             <DocPaginator metadata={metadata} />
@@ -120,12 +99,15 @@ function DocItem(props) {
         </div>
         {renderTocDesktop && (
           <div className="col col--3">
-            <TOC toc={DocContent.toc} />
+            <TOC
+              toc={DocContent.toc}
+              minHeadingLevel={tocMinHeadingLevel}
+              maxHeadingLevel={tocMaxHeadingLevel}
+              className={ThemeClassNames.docs.docTocDesktop}
+            />
           </div>
         )}
       </div>
     </>
   );
 }
-
-export default DocItem;

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

@@ -5,26 +5,16 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-.docItemContainer article *:first-child,
+.docItemContainer article > *:first-child,
 .docItemContainer header + * {
   margin-top: 0;
 }
 
-.lastUpdated {
-  margin-top: 0.2rem;
-  font-style: italic;
-  font-size: smaller;
-}
-
-@media only screen and (min-width: 997px) {
+@media (min-width: 997px) {
   .docItemCol {
     max-width: 75% !important;
   }
 
-  .lastUpdated {
-    text-align: right;
-  }
-
   /* Prevent hydration FOUC, as the mobile TOC needs to be server-rendered */
   .tocMobile {
     display: none;

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

@@ -0,0 +1,79 @@
+/**
+ * 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 LastUpdated from '@theme/LastUpdated';
+import EditThisPage from '@theme/EditThisPage';
+import TagsListInline from '@theme/TagsListInline';
+import styles from './styles.module.css';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+
+function TagsRow(props) {
+  return (
+    <div
+      className={clsx(
+        ThemeClassNames.docs.docFooterTagsRow,
+        'row margin-bottom--sm',
+      )}>
+      <div className="col">
+        <TagsListInline {...props} />
+      </div>
+    </div>
+  );
+}
+
+function EditMetaRow({
+  editUrl,
+  lastUpdatedAt,
+  lastUpdatedBy,
+  formattedLastUpdatedAt,
+}) {
+  return (
+    <div className={clsx(ThemeClassNames.docs.docFooterEditMetaRow, 'row')}>
+      <div className="col">{editUrl && <EditThisPage editUrl={editUrl} />}</div>
+
+      <div className={clsx('col', styles.lastUpdated)}>
+        {(lastUpdatedAt || lastUpdatedBy) && (
+          <LastUpdated
+            lastUpdatedAt={lastUpdatedAt}
+            formattedLastUpdatedAt={formattedLastUpdatedAt}
+            lastUpdatedBy={lastUpdatedBy}
+          />
+        )}
+      </div>
+    </div>
+  );
+}
+
+export default function DocItemFooter(props) {
+  const {content: DocContent} = props;
+  const {metadata} = DocContent;
+  const {editUrl, lastUpdatedAt, formattedLastUpdatedAt, lastUpdatedBy, tags} =
+    metadata;
+  const canDisplayTagsRow = tags.length > 0;
+  const canDisplayEditMetaRow = !!(editUrl || lastUpdatedAt || lastUpdatedBy);
+  const canDisplayFooter = canDisplayTagsRow || canDisplayEditMetaRow;
+
+  if (!canDisplayFooter) {
+    return <></>;
+  }
+
+  return (
+    <footer
+      className={clsx(ThemeClassNames.docs.docFooter, 'docusaurus-mt-lg')}>
+      {canDisplayTagsRow && <TagsRow tags={tags} />}
+      {canDisplayEditMetaRow && (
+        <EditMetaRow
+          editUrl={editUrl}
+          lastUpdatedAt={lastUpdatedAt}
+          lastUpdatedBy={lastUpdatedBy}
+          formattedLastUpdatedAt={formattedLastUpdatedAt}
+        />
+      )}
+    </footer>
+  );
+}

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

@@ -0,0 +1,18 @@
+/**
+ * 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.
+ */
+
+.lastUpdated {
+  margin-top: 0.2rem;
+  font-style: italic;
+  font-size: smaller;
+}
+
+@media (min-width: 997px) {
+  .lastUpdated {
+    text-align: right;
+  }
+}

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

@@ -6,7 +6,6 @@
  */
 import React, {useState, useCallback} from 'react';
 import {MDXProvider} from '@mdx-js/react';
-import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import renderRoutes from '@docusaurus/renderRoutes';
 import Layout from '@theme/Layout';
 import DocSidebar from '@theme/DocSidebar';
@@ -19,9 +18,9 @@ import {translate} from '@docusaurus/Translate';
 import clsx from 'clsx';
 import styles from './styles.module.css';
 import {ThemeClassNames, docVersionSearchTag} from '@docusaurus/theme-common';
+import Head from '@docusaurus/Head';
 
 function DocPageContent({currentDocRoute, versionMetadata, children}) {
-  const {isClient} = useDocusaurusContext();
   const {pluginId, version} = versionMetadata;
   const sidebarName = currentDocRoute.sidebar;
   const sidebar = sidebarName
@@ -34,13 +33,12 @@ function DocPageContent({currentDocRoute, versionMetadata, children}) {
       setHiddenSidebar(false);
     }
 
-    setHiddenSidebarContainer(!hiddenSidebarContainer);
+    setHiddenSidebarContainer((value) => !value);
   }, [hiddenSidebar]);
   return (
     <Layout
-      key={isClient}
-      wrapperClassName={ThemeClassNames.wrapper.docPages}
-      pageClassName={ThemeClassNames.page.docPage}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsDocPage}
       searchMetadatas={{
         version,
         tag: docVersionSearchTag(pluginId, version),
@@ -132,17 +130,23 @@ function DocPage(props) {
   );
 
   if (!currentDocRoute) {
-    return <NotFound {...props} />;
+    return <NotFound />;
   }
 
   return (
-    <DocPageContent
-      currentDocRoute={currentDocRoute}
-      versionMetadata={versionMetadata}>
-      {renderRoutes(docRoutes, {
-        versionMetadata,
-      })}
-    </DocPageContent>
+    <>
+      <Head>
+        {/* TODO we should add a core addRoute({htmlClassName}) generic plugin option */}
+        <html className={versionMetadata.className} />
+      </Head>
+      <DocPageContent
+        currentDocRoute={currentDocRoute}
+        versionMetadata={versionMetadata}>
+        {renderRoutes(docRoutes, {
+          versionMetadata,
+        })}
+      </DocPageContent>
+    </>
   );
 }
 

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

@@ -10,9 +10,10 @@ import {
   useThemeConfig,
   useAnnouncementBar,
   MobileSecondaryMenuFiller,
+  ThemeClassNames,
+  useScrollPosition,
 } from '@docusaurus/theme-common';
 import useWindowSize from '@theme/hooks/useWindowSize';
-import useScrollPosition from '@theme/hooks/useScrollPosition';
 import Logo from '@theme/Logo';
 import IconArrow from '@theme/IconArrow';
 import {translate} from '@docusaurus/Translate';
@@ -20,14 +21,17 @@ import {DocSidebarItems} from '@theme/DocSidebarItem';
 import styles from './styles.module.css';
 
 function useShowAnnouncementBar() {
-  const {isClosed} = useAnnouncementBar();
-  const [showAnnouncementBar, setShowAnnouncementBar] = useState(!isClosed);
-  useScrollPosition(({scrollY}) => {
-    if (!isClosed) {
-      setShowAnnouncementBar(scrollY === 0);
-    }
-  });
-  return showAnnouncementBar;
+  const {isActive} = useAnnouncementBar();
+  const [showAnnouncementBar, setShowAnnouncementBar] = useState(isActive);
+  useScrollPosition(
+    ({scrollY}) => {
+      if (isActive) {
+        setShowAnnouncementBar(scrollY === 0);
+      }
+    },
+    [isActive],
+  );
+  return isActive && showAnnouncementBar;
 }
 
 function HideableSidebarButton({onClick}) {
@@ -60,7 +64,6 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}) {
     navbar: {hideOnScroll},
     hideableSidebar,
   } = useThemeConfig();
-  const {isClosed: isAnnouncementBarClosed} = useAnnouncementBar();
   return (
     <div
       className={clsx(styles.sidebar, {
@@ -70,11 +73,10 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}) {
       {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
       <nav
         className={clsx('menu thin-scrollbar', styles.menu, {
-          [styles.menuWithAnnouncementBar]:
-            !isAnnouncementBarClosed && showAnnouncementBar,
+          [styles.menuWithAnnouncementBar]: showAnnouncementBar,
         })}>
-        <ul className="menu__list">
-          <DocSidebarItems items={sidebar} activePath={path} />
+        <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
+          <DocSidebarItems items={sidebar} activePath={path} level={1} />
         </ul>
       </nav>
       {hideableSidebar && <HideableSidebarButton onClick={onCollapse} />}
@@ -84,11 +86,12 @@ function DocSidebarDesktop({path, sidebar, onCollapse, isHidden}) {
 
 const DocSidebarMobileSecondaryMenu = ({toggleSidebar, sidebar, path}) => {
   return (
-    <ul className="menu__list">
+    <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, 'menu__list')}>
       <DocSidebarItems
         items={sidebar}
         activePath={path}
         onItemClick={() => toggleSidebar()}
+        level={1}
       />
     </ul>
   );

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

@@ -11,6 +11,7 @@ import {
   usePrevious,
   Collapsible,
   useCollapsible,
+  ThemeClassNames,
 } from '@docusaurus/theme-common';
 import Link from '@docusaurus/Link';
 import isInternalUrl from '@docusaurus/isInternalUrl';
@@ -72,11 +73,17 @@ function useAutoExpandActiveCategory({isActive, collapsed, setCollapsed}) {
     if (justBecameActive && collapsed) {
       setCollapsed(false);
     }
-  }, [isActive, wasActive, collapsed]);
+  }, [isActive, wasActive, collapsed, setCollapsed]);
 }
 
-function DocSidebarItemCategory({item, onItemClick, activePath, ...props}) {
-  const {items, label, collapsible} = item;
+function DocSidebarItemCategory({
+  item,
+  onItemClick,
+  activePath,
+  level,
+  ...props
+}) {
+  const {items, label, collapsible, className} = item;
   const isActive = isActiveSidebarItem(item, activePath);
   const {collapsed, setCollapsed, toggleCollapsed} = useCollapsible({
     // active categories are always initialized as expanded
@@ -96,9 +103,15 @@ function DocSidebarItemCategory({item, onItemClick, activePath, ...props}) {
   });
   return (
     <li
-      className={clsx('menu__list-item', {
-        'menu__list-item--collapsed': collapsed,
-      })}>
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemCategory,
+        ThemeClassNames.docs.docSidebarItemCategoryLevel(level),
+        'menu__list-item',
+        {
+          'menu__list-item--collapsed': collapsed,
+        },
+        className,
+      )}>
       {/* eslint-disable-next-line jsx-a11y/anchor-is-valid */}
       <a
         className={clsx('menu__link', {
@@ -125,25 +138,32 @@ function DocSidebarItemCategory({item, onItemClick, activePath, ...props}) {
           tabIndex={collapsed ? -1 : 0}
           onItemClick={onItemClick}
           activePath={activePath}
+          level={level + 1}
         />
       </Collapsible>
     </li>
   );
 }
 
-function DocSidebarItemLink({item, onItemClick, activePath, ...props}) {
-  const {href, label} = item;
+function DocSidebarItemLink({item, onItemClick, activePath, level, ...props}) {
+  const {href, label, className} = item;
   const isActive = isActiveSidebarItem(item, activePath);
   return (
-    <li className="menu__list-item" key={label}>
+    <li
+      className={clsx(
+        ThemeClassNames.docs.docSidebarItemLink,
+        ThemeClassNames.docs.docSidebarItemLinkLevel(level),
+        'menu__list-item',
+        className,
+      )}
+      key={label}>
       <Link
         className={clsx('menu__link', {
           'menu__link--active': isActive,
         })}
+        aria-current={isActive ? 'page' : undefined}
         to={href}
         {...(isInternalUrl(href) && {
-          isNavLink: true,
-          exact: true,
           onClick: onItemClick,
         })}
         {...props}>

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

@@ -0,0 +1,89 @@
+/**
+ * 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 Layout from '@theme/Layout';
+import Link from '@docusaurus/Link';
+import {ThemeClassNames, usePluralForm} from '@docusaurus/theme-common';
+import Translate, {translate} from '@docusaurus/Translate';
+
+// Very simple pluralization: probably good enough for now
+function useNDocsTaggedPlural() {
+  const {selectMessage} = usePluralForm();
+  return (count) =>
+    selectMessage(
+      count,
+      translate(
+        {
+          id: 'theme.docs.tagDocListPageTitle.nDocsTagged',
+          description:
+            'Pluralized label for "{count} docs tagged". Use as much plural forms (separated by "|") as your language support (see https://www.unicode.org/cldr/cldr-aux/charts/34/supplemental/language_plural_rules.html)',
+          message: 'One doc tagged|{count} docs tagged',
+        },
+        {
+          count,
+        },
+      ),
+    );
+}
+
+function DocItem({doc}) {
+  return (
+    <article className="margin-vert--lg">
+      <Link to={doc.permalink}>
+        <h2>{doc.title}</h2>
+      </Link>
+      {doc.description && <p>{doc.description}</p>}
+    </article>
+  );
+}
+
+export default function DocTagDocListPage({tag}) {
+  const nDocsTaggedPlural = useNDocsTaggedPlural();
+  const title = translate(
+    {
+      id: 'theme.docs.tagDocListPageTitle',
+      description: 'The title of the page for a docs tag',
+      message: '{nDocsTagged} with "{tagName}"',
+    },
+    {
+      nDocsTagged: nDocsTaggedPlural(tag.docs.length),
+      tagName: tag.name,
+    },
+  );
+  return (
+    <Layout
+      title={title}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsTagDocListPage}
+      searchMetadatas={{
+        // assign unique search tag to exclude this page from search results!
+        tag: 'doc_tag_doc_list',
+      }}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            <header className="margin-bottom--xl">
+              <h1>{title}</h1>
+              <Link href={tag.allTagsPath}>
+                <Translate
+                  id="theme.tags.tagsPageLink"
+                  description="The label of the link targeting the tag list page">
+                  View All Tags
+                </Translate>
+              </Link>
+            </header>
+            <section className="margin-vert--lg">
+              {tag.docs.map((doc) => (
+                <DocItem key={doc.id} doc={doc} />
+              ))}
+            </section>
+          </main>
+        </div>
+      </div>
+    </Layout>
+  );
+}

package/lib-next/theme/DocTagsListPage/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 Layout from '@theme/Layout';
+import {
+  ThemeClassNames,
+  translateTagsPageTitle,
+} from '@docusaurus/theme-common';
+import TagsListByLetter from '@theme/TagsListByLetter';
+
+function DocTagsListPage({tags}) {
+  const title = translateTagsPageTitle();
+  return (
+    <Layout
+      title={title}
+      wrapperClassName={ThemeClassNames.wrapper.docsPages}
+      pageClassName={ThemeClassNames.page.docsTagsListPage}
+      searchMetadatas={{
+        // assign unique search tag to exclude this page from search results!
+        tag: 'doc_tags_list',
+      }}>
+      <div className="container margin-vert--lg">
+        <div className="row">
+          <main className="col col--8 col--offset-2">
+            <h1>{title}</h1>
+            <TagsListByLetter tags={tags} />
+          </main>
+        </div>
+      </div>
+    </Layout>
+  );
+}
+
+export default DocTagsListPage;

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

@@ -9,7 +9,11 @@ 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';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+} from '@docusaurus/theme-common';
+import clsx from 'clsx';
 
 function UnreleasedVersionLabel({siteTitle, versionMetadata}) {
   return (
@@ -92,16 +96,19 @@ function DocVersionBannerEnabled({versionMetadata}) {
     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)
+  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
+      className={clsx(
+        ThemeClassNames.docs.docVersionBanner,
+        'alert alert--warning margin-bottom--md',
+      )}
+      role="alert">
       <div>
         <BannerLabel siteTitle={siteTitle} versionMetadata={versionMetadata} />
       </div>
@@ -117,11 +124,11 @@ function DocVersionBannerEnabled({versionMetadata}) {
 }
 
 function DocVersionBanner({versionMetadata}) {
-  if (versionMetadata.banner === 'none') {
-    return <></>;
-  } else {
+  if (versionMetadata.banner) {
     return <DocVersionBannerEnabled versionMetadata={versionMetadata} />;
   }
+
+  return <></>;
 }
 
 export default DocVersionBanner;

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

@@ -7,9 +7,14 @@
 import React from 'react';
 import Translate from '@docusaurus/Translate';
 import IconEdit from '@theme/IconEdit';
+import {ThemeClassNames} from '@docusaurus/theme-common';
 export default function EditThisPage({editUrl}) {
   return (
-    <a href={editUrl} target="_blank" rel="noreferrer noopener">
+    <a
+      href={editUrl}
+      target="_blank"
+      rel="noreferrer noopener"
+      className={ThemeClassNames.common.editThisPage}>
       <IconEdit />
       <Translate
         id="theme.common.editThisPage"