@docusaurus/theme-classic 2.0.0-beta.ff31de0ff → 2.0.1

package/src/theme/DocSidebarItem/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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 DocSidebarItemCategory from '@theme/DocSidebarItem/Category';
+import DocSidebarItemLink from '@theme/DocSidebarItem/Link';
+import DocSidebarItemHtml from '@theme/DocSidebarItem/Html';
+import type {Props} from '@theme/DocSidebarItem';
+
+export default function DocSidebarItem({
+  item,
+  ...props
+}: Props): JSX.Element | null {
+  switch (item.type) {
+    case 'category':
+      return <DocSidebarItemCategory item={item} {...props} />;
+    case 'html':
+      return <DocSidebarItemHtml item={item} {...props} />;
+    case 'link':
+    default:
+      return <DocSidebarItemLink item={item} {...props} />;
+  }
+}

package/src/theme/DocSidebarItems/index.tsx

@@ -0,0 +1,27 @@
+/**
+ * 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, {memo} from 'react';
+import {DocSidebarItemsExpandedStateProvider} from '@docusaurus/theme-common/internal';
+import DocSidebarItem from '@theme/DocSidebarItem';
+
+import type {Props} from '@theme/DocSidebarItems';
+
+// TODO this item should probably not receive the "activePath" props
+// TODO this triggers whole sidebar re-renders on navigation
+function DocSidebarItems({items, ...props}: Props): JSX.Element {
+  return (
+    <DocSidebarItemsExpandedStateProvider>
+      {items.map((item, index) => (
+        <DocSidebarItem key={index} item={item} index={index} {...props} />
+      ))}
+    </DocSidebarItemsExpandedStateProvider>
+  );
+}
+
+// Optimize sidebar at each "level"
+export default memo(DocSidebarItems);

package/src/theme/DocTagDocListPage/index.tsx

@@ -0,0 +1,95 @@
+/**
+ * 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 Link from '@docusaurus/Link';
+import {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+  usePluralForm,
+} from '@docusaurus/theme-common';
+import Translate, {translate} from '@docusaurus/Translate';
+import Layout from '@theme/Layout';
+import SearchMetadata from '@theme/SearchMetadata';
+import type {Props} from '@theme/DocTagDocListPage';
+
+// Very simple pluralization: probably good enough for now
+function useNDocsTaggedPlural() {
+  const {selectMessage} = usePluralForm();
+  return (count: number) =>
+    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}: {doc: Props['tag']['items'][number]}): JSX.Element {
+  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}: Props): JSX.Element {
+  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.count), tagName: tag.label},
+  );
+
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.docsPages,
+        ThemeClassNames.page.docsTagDocListPage,
+      )}>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="doc_tag_doc_list" />
+      <Layout>
+        <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.items.map((doc) => (
+                  <DocItem key={doc.id} doc={doc} />
+                ))}
+              </section>
+            </main>
+          </div>
+        </div>
+      </Layout>
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/DocTagsListPage/index.tsx

@@ -0,0 +1,43 @@
+/**
+ * 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 {
+  PageMetadata,
+  HtmlClassNameProvider,
+  ThemeClassNames,
+  translateTagsPageTitle,
+} from '@docusaurus/theme-common';
+import Layout from '@theme/Layout';
+import TagsListByLetter from '@theme/TagsListByLetter';
+import SearchMetadata from '@theme/SearchMetadata';
+import type {Props} from '@theme/DocTagsListPage';
+
+export default function DocTagsListPage({tags}: Props): JSX.Element {
+  const title = translateTagsPageTitle();
+  return (
+    <HtmlClassNameProvider
+      className={clsx(
+        ThemeClassNames.wrapper.docsPages,
+        ThemeClassNames.page.docsTagsListPage,
+      )}>
+      <PageMetadata title={title} />
+      <SearchMetadata tag="doc_tags_list" />
+      <Layout>
+        <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>
+    </HtmlClassNameProvider>
+  );
+}

package/src/theme/DocVersionBadge/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * 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 {ThemeClassNames} from '@docusaurus/theme-common';
+import {useDocsVersion} from '@docusaurus/theme-common/internal';
+import type {Props} from '@theme/DocVersionBadge';
+
+export default function DocVersionBadge({
+  className,
+}: Props): JSX.Element | null {
+  const versionMetadata = useDocsVersion();
+  if (versionMetadata.badge) {
+    return (
+      <span
+        className={clsx(
+          className,
+          ThemeClassNames.docs.docVersionBadge,
+          'badge badge--secondary',
+        )}>
+        <Translate
+          id="theme.docs.versionBadge.label"
+          values={{versionLabel: versionMetadata.label}}>
+          {'Version: {versionLabel}'}
+        </Translate>
+      </span>
+    );
+  }
+  return null;
+}

package/src/theme/{DocVersionSuggestions → DocVersionBanner}/index.tsx

@@ -5,31 +5,43 @@
  * LICENSE file in the root directory of this source tree.
  */
 
-import React from 'react';
+import React, {type ComponentType} from 'react';
+import clsx from 'clsx';
 import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
 import Link from '@docusaurus/Link';
 import Translate from '@docusaurus/Translate';
 import {
   useActivePlugin,
-  useActiveVersion,
   useDocVersionSuggestions,
-} from '@theme/hooks/useDocs';
-import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+  type GlobalVersion,
+} from '@docusaurus/plugin-content-docs/client';
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import {
+  useDocsPreferredVersion,
+  useDocsVersion,
+} from '@docusaurus/theme-common/internal';
+import type {Props} from '@theme/DocVersionBanner';
+import type {
+  VersionBanner,
+  PropVersionMetadata,
+} from '@docusaurus/plugin-content-docs';
+
+type BannerLabelComponentProps = {
+  siteTitle: string;
+  versionMetadata: PropVersionMetadata;
+};
 
 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 +52,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 +69,19 @@ function UnmaintainedVersionLabel({
   );
 }
 
+const BannerLabelComponents: {
+  [banner in VersionBanner]: 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 +94,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 +106,7 @@ function LatestVersionSuggestionLabel({
                 latest version
               </Translate>
             </Link>
-          </strong>
+          </b>
         ),
       }}>
       {
@@ -94,47 +116,40 @@ function LatestVersionSuggestionLabel({
   );
 }
 
-const getVersionMainDoc = (version) =>
-  version.docs.find((doc) => doc.id === version.mainDocId);
-
-function DocVersionSuggestions(): JSX.Element {
+function DocVersionBannerEnabled({
+  className,
+  versionMetadata,
+}: Props & {
+  versionMetadata: PropVersionMetadata;
+}): JSX.Element {
   const {
     siteConfig: {title: siteTitle},
   } = useDocusaurusContext();
-  const {pluginId} = useActivePlugin({failfast: true});
+  const {pluginId} = useActivePlugin({failfast: true})!;
 
-  const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
+  const getVersionMainDoc = (version: GlobalVersion) =>
+    version.docs.find((doc) => doc.id === version.mainDocId)!;
 
-  const activeVersion = useActiveVersion(pluginId);
-  const {
-    latestDocSuggestion,
-    latestVersionSuggestion,
-  } = useDocVersionSuggestions(pluginId);
+  const {savePreferredVersionName} = useDocsPreferredVersion(pluginId);
 
-  // No suggestion to be made
-  if (!latestVersionSuggestion) {
-    return <></>;
-  }
+  const {latestDocSuggestion, latestVersionSuggestion} =
+    useDocVersionSuggestions(pluginId);
 
-  // try to link to same doc in latest version (not always possible)
-  // fallback to main doc of latest version
+  // Try to link to same doc in latest version (not always possible), falling
+  // back 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(
+        className,
+        ThemeClassNames.docs.docVersionBanner,
+        '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 +162,17 @@ function DocVersionSuggestions(): JSX.Element {
   );
 }
 
-export default DocVersionSuggestions;
+export default function DocVersionBanner({
+  className,
+}: Props): JSX.Element | null {
+  const versionMetadata = useDocsVersion();
+  if (versionMetadata.banner) {
+    return (
+      <DocVersionBannerEnabled
+        className={className}
+        versionMetadata={versionMetadata}
+      />
+    );
+  }
+  return null;
+}

package/src/theme/EditThisPage/index.tsx

@@ -7,13 +7,17 @@
 
 import React from 'react';
 import Translate from '@docusaurus/Translate';
-
+import {ThemeClassNames} from '@docusaurus/theme-common';
+import IconEdit from '@theme/Icon/Edit';
 import type {Props} from '@theme/EditThisPage';
-import IconEdit from '@theme/IconEdit';
 
 export default function EditThisPage({editUrl}: Props): JSX.Element {
   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"

package/src/theme/ErrorPageContent.tsx

@@ -0,0 +1,41 @@
+/**
+ * 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 type {Props} from '@theme/Error';
+
+export default function ErrorPageContent({
+  error,
+  tryAgain,
+}: Props): JSX.Element {
+  return (
+    <main className="container margin-vert--xl">
+      <div className="row">
+        <div className="col col--6 col--offset-3">
+          <h1 className="hero__title">
+            <Translate
+              id="theme.ErrorPageContent.title"
+              description="The title of the fallback page when the page crashed">
+              This page crashed.
+            </Translate>
+          </h1>
+          <p>{error.message}</p>
+          <div>
+            <button type="button" onClick={tryAgain}>
+              <Translate
+                id="theme.ErrorPageContent.tryAgain"
+                description="The label of the button to try again when the page crashed">
+                Try again
+              </Translate>
+            </button>
+          </div>
+        </div>
+      </div>
+    </main>
+  );
+}

package/src/theme/Footer/Copyright/index.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/Footer/Copyright';
+
+export default function FooterCopyright({copyright}: Props): JSX.Element {
+  return (
+    <div
+      className="footer__copyright"
+      // Developer provided the HTML, so assume it's safe.
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: copyright}}
+    />
+  );
+}

package/src/theme/Footer/Layout/index.tsx

@@ -0,0 +1,34 @@
+/**
+ * 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 type {Props} from '@theme/Footer/Layout';
+
+export default function FooterLayout({
+  style,
+  links,
+  logo,
+  copyright,
+}: Props): JSX.Element {
+  return (
+    <footer
+      className={clsx('footer', {
+        'footer--dark': style === 'dark',
+      })}>
+      <div className="container container-fluid">
+        {links}
+        {(logo || copyright) && (
+          <div className="footer__bottom text--center">
+            {logo && <div className="margin-bottom--sm">{logo}</div>}
+            {copyright}
+          </div>
+        )}
+      </div>
+    </footer>
+  );
+}

package/src/theme/Footer/LinkItem/index.tsx

@@ -0,0 +1,36 @@
+/**
+ * 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 isInternalUrl from '@docusaurus/isInternalUrl';
+import IconExternalLink from '@theme/Icon/ExternalLink';
+import type {Props} from '@theme/Footer/LinkItem';
+
+export default function FooterLinkItem({item}: Props): JSX.Element {
+  const {to, href, label, prependBaseUrlToHref, ...props} = item;
+  const toUrl = useBaseUrl(to);
+  const normalizedHref = useBaseUrl(href, {forcePrependBaseUrl: true});
+
+  return (
+    <Link
+      className="footer__link-item"
+      {...(href
+        ? {
+            href: prependBaseUrlToHref ? normalizedHref : href,
+          }
+        : {
+            to: toUrl,
+          })}
+      {...props}>
+      {label}
+      {href && !isInternalUrl(href) && <IconExternalLink />}
+    </Link>
+  );
+}

package/src/theme/Footer/Links/MultiColumn/index.tsx

@@ -0,0 +1,51 @@
+/**
+ * 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 LinkItem from '@theme/Footer/LinkItem';
+import type {Props} from '@theme/Footer/Links/MultiColumn';
+
+type ColumnType = Props['columns'][number];
+type ColumnItemType = ColumnType['items'][number];
+
+function ColumnLinkItem({item}: {item: ColumnItemType}) {
+  return item.html ? (
+    <li
+      className="footer__item"
+      // Developer provided the HTML, so assume it's safe.
+      // eslint-disable-next-line react/no-danger
+      dangerouslySetInnerHTML={{__html: item.html}}
+    />
+  ) : (
+    <li key={item.href ?? item.to} className="footer__item">
+      <LinkItem item={item} />
+    </li>
+  );
+}
+
+function Column({column}: {column: ColumnType}) {
+  return (
+    <div className="col footer__col">
+      <div className="footer__title">{column.title}</div>
+      <ul className="footer__items clean-list">
+        {column.items.map((item, i) => (
+          <ColumnLinkItem key={i} item={item} />
+        ))}
+      </ul>
+    </div>
+  );
+}
+
+export default function FooterLinksMultiColumn({columns}: Props): JSX.Element {
+  return (
+    <div className="row footer__links">
+      {columns.map((column, i) => (
+        <Column key={i} column={column} />
+      ))}
+    </div>
+  );
+}