You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@pulsar.apache.org by ur...@apache.org on 2022/03/31 05:24:15 UTC

[pulsar-site] 01/01: feat: add versions dropdown menu in docs page

This is an automated email from the ASF dual-hosted git repository.

urfree pushed a commit to branch feature/versions-in-docs-sidebar
in repository https://gitbox.apache.org/repos/asf/pulsar-site.git

commit a7b593365034ddfa6685b5eaaae49a9e233d69b8
Author: Li Li <ur...@apache.org>
AuthorDate: Thu Mar 31 13:23:50 2022 +0800

    feat: add versions dropdown menu in docs page
    
    Signed-off-by: Li Li <ur...@apache.org>
---
 site2/website-next/src/css/custom.css              |   4 +
 .../src/theme/DocSidebar/Desktop/index.js          |  59 +++++++++
 .../src/theme/DocSidebar/Desktop/styles.module.css |  68 ++++++++++
 .../src/theme/DocSidebar/Mobile/index.js           |  68 ++++++++++
 .../src/theme/DocSidebar/Mobile/styles.module.css  |  23 ++++
 site2/website-next/src/theme/DocSidebar/index.js   |  24 ++++
 .../src/theme/DocVersionBanner/index.js            | 144 +++++++++++++++++++++
 .../src/theme/DocsVersionDropdownNavbarItem.js     |  97 ++++++++++++++
 8 files changed, 487 insertions(+)

diff --git a/site2/website-next/src/css/custom.css b/site2/website-next/src/css/custom.css
index 39730db..1b80c5d 100644
--- a/site2/website-next/src/css/custom.css
+++ b/site2/website-next/src/css/custom.css
@@ -899,4 +899,8 @@ footer .row.footer__links {
 }
 @media (max-width: 400px){
   .row.footer__links .footer__col:first-child  .footer-items .footer__item a { font-size: 14px;}
+}
+
+.sidebarVersionSwitch_src-theme-DocSidebar-Desktop-styles-module .dropdown__menu {
+  min-width: 165px !important;
 }
\ No newline at end of file
diff --git a/site2/website-next/src/theme/DocSidebar/Desktop/index.js b/site2/website-next/src/theme/DocSidebar/Desktop/index.js
new file mode 100644
index 0000000..166bfe4
--- /dev/null
+++ b/site2/website-next/src/theme/DocSidebar/Desktop/index.js
@@ -0,0 +1,59 @@
+/**
+ * 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 { useThemeConfig } from "@docusaurus/theme-common";
+import Logo from "@theme/Logo";
+import CollapseButton from "@theme/DocSidebar/Desktop/CollapseButton";
+import Content from "@theme/DocSidebar/Desktop/Content";
+import styles from "./styles.module.css";
+import DocsVersionDropdownNavbarItem from "@theme/NavbarItem/DocsVersionDropdownNavbarItem";
+
+function DocSidebarDesktop({
+  path,
+  sidebar,
+  onCollapse,
+  isHidden,
+  docsPluginId,
+}) {
+  const {
+    navbar: { hideOnScroll },
+    hideableSidebar,
+  } = useThemeConfig();
+  return (
+    <div
+      className={clsx(
+        styles.sidebar,
+        hideOnScroll && styles.sidebarWithHideableNavbar,
+        isHidden && styles.sidebarHidden
+      )}
+    >
+      {hideOnScroll && <Logo tabIndex={-1} className={styles.sidebarLogo} />}
+      <DocsVersionWrapperMemo docsPluginId={docsPluginId} />
+      <Content path={path} sidebar={sidebar} />
+      {hideableSidebar && <CollapseButton onClick={onCollapse} />}
+    </div>
+  );
+}
+
+function DocsVersionWrapper(props) {
+  return (
+    <div className={styles.sidebarVersionSwitch}>
+      Version:
+      <DocsVersionDropdownNavbarItem
+        docsPluginId={props.docsPluginId}
+        dropdownItemsBefore={[]}
+        dropdownItemsAfter={[]}
+        items={['Master', 'Legacy']}
+      />
+    </div>
+  );
+}
+
+const DocsVersionWrapperMemo = React.memo(DocsVersionWrapper);
+
+export default React.memo(DocSidebarDesktop);
diff --git a/site2/website-next/src/theme/DocSidebar/Desktop/styles.module.css b/site2/website-next/src/theme/DocSidebar/Desktop/styles.module.css
new file mode 100644
index 0000000..16d3c38
--- /dev/null
+++ b/site2/website-next/src/theme/DocSidebar/Desktop/styles.module.css
@@ -0,0 +1,68 @@
+/**
+ * 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.
+ */
+
+@media (min-width: 997px) {
+  .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 {
+    padding-top: 0;
+  }
+
+  .sidebarHidden {
+    opacity: 0;
+    height: 0;
+    overflow: hidden;
+    visibility: hidden;
+  }
+
+  .sidebarLogo {
+    display: flex !important;
+    align-items: center;
+    margin: 0 var(--ifm-navbar-padding-horizontal);
+    min-height: var(--ifm-navbar-height);
+    max-height: var(--ifm-navbar-height);
+    color: inherit !important;
+    text-decoration: none !important;
+  }
+
+  .sidebarLogo img {
+    margin-right: 0.5rem;
+    height: 2rem;
+  }
+}
+
+.sidebarLogo {
+  display: none;
+}
+
+.sidebarVersionSwitch {
+  display: flex;
+  align-items: center;
+  padding: 4px 1rem;
+  margin: 1rem;
+  border-radius: 0.5rem;
+  border: 1px solid #198fff;
+  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.03);
+}
+
+.sidebarVersionSwitch a {
+  display: inline-block;
+}
+
+.sidebarVersionSwitch div {
+  display: inline-block !important;
+}
diff --git a/site2/website-next/src/theme/DocSidebar/Mobile/index.js b/site2/website-next/src/theme/DocSidebar/Mobile/index.js
new file mode 100644
index 0000000..c4d1d4e
--- /dev/null
+++ b/site2/website-next/src/theme/DocSidebar/Mobile/index.js
@@ -0,0 +1,68 @@
+/**
+ * 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 {
+  NavbarSecondaryMenuFiller,
+  ThemeClassNames,
+  useNavbarMobileSidebar,
+} from "@docusaurus/theme-common";
+import DocSidebarItems from "@theme/DocSidebarItems";
+import styles from "./styles.module.css";
+import DocsVersionDropdownNavbarItem from "@theme/NavbarItem/DocsVersionDropdownNavbarItem";
+
+// eslint-disable-next-line react/function-component-definition
+const DocSidebarMobileSecondaryMenu = ({ sidebar, path, docsPluginId }) => {
+  const mobileSidebar = useNavbarMobileSidebar();
+  return (
+    <ul className={clsx(ThemeClassNames.docs.docSidebarMenu, "menu__list")}>
+      <DocsVersionWrapperMemo docsPluginId={docsPluginId} />
+      <DocSidebarItems
+        items={sidebar}
+        activePath={path}
+        onItemClick={(item) => {
+          // Mobile sidebar should only be closed if the category has a link
+          if (item.type === "category" && item.href) {
+            mobileSidebar.toggle();
+          }
+
+          if (item.type === "link") {
+            mobileSidebar.toggle();
+          }
+        }}
+        level={1}
+      />
+    </ul>
+  );
+};
+
+function DocSidebarMobile(props) {
+  return (
+    <NavbarSecondaryMenuFiller
+      component={DocSidebarMobileSecondaryMenu}
+      props={props}
+    />
+  );
+}
+
+function DocsVersionWrapper(props) {
+  return (
+    <div className={styles.sidebarVersionSwitch}>
+      Version:
+      <DocsVersionDropdownNavbarItem
+        docsPluginId={props.docsPluginId}
+        dropdownItemsBefore={[]}
+        dropdownItemsAfter={[]}
+        items={["Master", "Legacy"]}
+      />
+    </div>
+  );
+}
+
+const DocsVersionWrapperMemo = React.memo(DocsVersionWrapper);
+
+export default React.memo(DocSidebarMobile);
diff --git a/site2/website-next/src/theme/DocSidebar/Mobile/styles.module.css b/site2/website-next/src/theme/DocSidebar/Mobile/styles.module.css
new file mode 100644
index 0000000..9527b6e
--- /dev/null
+++ b/site2/website-next/src/theme/DocSidebar/Mobile/styles.module.css
@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+.sidebarVersionSwitch {
+  display: flex;
+  align-items: center;
+  padding: 4px 1rem;
+  margin: 1rem;
+  border-radius: 0.5rem;
+  border: 1px solid #198fff;
+  box-shadow: 0 1px 2px 0 rgba(0, 0, 0, 0.03);
+}
+
+.sidebarVersionSwitch a {
+  display: inline-block;
+}
+
+.sidebarVersionSwitch div {
+  display: inline-block !important;
+}
diff --git a/site2/website-next/src/theme/DocSidebar/index.js b/site2/website-next/src/theme/DocSidebar/index.js
new file mode 100644
index 0000000..a84c73a
--- /dev/null
+++ b/site2/website-next/src/theme/DocSidebar/index.js
@@ -0,0 +1,24 @@
+/**
+ * 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 {useWindowSize} from '@docusaurus/theme-common';
+import DocSidebarDesktop from '@theme/DocSidebar/Desktop';
+import DocSidebarMobile from '@theme/DocSidebar/Mobile';
+export default function DocSidebar(props) {
+  const windowSize = useWindowSize(); // Desktop sidebar visible on hydration: need SSR rendering
+
+  const shouldRenderSidebarDesktop =
+    windowSize === 'desktop' || windowSize === 'ssr'; // Mobile sidebar not visible on hydration: can avoid SSR rendering
+
+  const shouldRenderSidebarMobile = windowSize === 'mobile';
+  return (
+    <>
+      {shouldRenderSidebarDesktop && <DocSidebarDesktop {...props} />}
+      {shouldRenderSidebarMobile && <DocSidebarMobile {...props} />}
+    </>
+  );
+}
diff --git a/site2/website-next/src/theme/DocVersionBanner/index.js b/site2/website-next/src/theme/DocVersionBanner/index.js
new file mode 100644
index 0000000..733d144
--- /dev/null
+++ b/site2/website-next/src/theme/DocVersionBanner/index.js
@@ -0,0 +1,144 @@
+/**
+ * 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 '@docusaurus/plugin-content-docs/client';
+import {
+  ThemeClassNames,
+  useDocsPreferredVersion,
+  useDocsVersion,
+} from '@docusaurus/theme-common';
+import clsx from 'clsx';
+
+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({className, 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={clsx(
+        className,
+        ThemeClassNames.docs.docVersionBanner,
+        '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>
+  );
+}
+
+export default function DocVersionBanner({className}) {
+  const versionMetadata = useDocsVersion();
+
+  if (versionMetadata.banner) {
+    return (
+      <DocVersionBannerEnabled
+        className={className}
+        versionMetadata={versionMetadata}
+      />
+    );
+  }
+
+  return null;
+}
diff --git a/site2/website-next/src/theme/DocsVersionDropdownNavbarItem.js b/site2/website-next/src/theme/DocsVersionDropdownNavbarItem.js
new file mode 100644
index 0000000..9d7a178
--- /dev/null
+++ b/site2/website-next/src/theme/DocsVersionDropdownNavbarItem.js
@@ -0,0 +1,97 @@
+/**
+ * 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 DefaultNavbarItem from '@theme/NavbarItem/DefaultNavbarItem';
+import DropdownNavbarItem from '@theme/NavbarItem/DropdownNavbarItem';
+import {
+  useVersions,
+  useLatestVersion,
+  useActiveDocContext,
+} from '@docusaurus/plugin-content-docs/client';
+import {useDocsPreferredVersion} from '@docusaurus/theme-common';
+import {translate} from '@docusaurus/Translate';
+
+const getVersionMainDoc = (version) =>
+  version.docs.find((doc) => doc.id === version.mainDocId);
+
+export default function DocsVersionDropdownNavbarItem({
+  mobile,
+  docsPluginId,
+  dropdownActiveClassDisabled,
+  dropdownItemsBefore,
+  dropdownItemsAfter,
+  ...props
+}) {
+  const activeDocContext = useActiveDocContext(docsPluginId);
+  const versions = useVersions(docsPluginId);
+  const latestVersion = useLatestVersion(docsPluginId);
+  const {preferredVersion, savePreferredVersionName} =
+    useDocsPreferredVersion(docsPluginId);
+
+  function getItems() {
+    const versionLinks = versions.map((version) => {
+      // We try to link to the same doc, in another version
+      // When not possible, fallback to the "main doc" of the version
+      const versionDoc =
+        activeDocContext?.alternateDocVersions[version.name] ||
+        getVersionMainDoc(version);
+      return {
+        isNavLink: true,
+        label: version.label,
+        to: versionDoc.path,
+        isActive: () => version === activeDocContext?.activeVersion,
+        onClick: () => {
+          savePreferredVersionName(version.name);
+        },
+      };
+    });
+    return [...dropdownItemsBefore, ...versionLinks, ...dropdownItemsAfter];
+  }
+
+  const items = getItems();
+  const dropdownVersion =
+    activeDocContext.activeVersion ?? preferredVersion ?? latestVersion; // Mobile dropdown is handled a bit differently
+
+  const dropdownLabel =
+    mobile && items.length > 1
+      ? translate({
+          id: 'theme.navbar.mobileVersionsDropdown.label',
+          message: 'Versions',
+          description:
+            'The label for the navbar versions dropdown on mobile view',
+        })
+      : dropdownVersion.label;
+  const dropdownTo =
+    mobile && items.length > 1
+      ? undefined
+      : getVersionMainDoc(dropdownVersion).path; // We don't want to render a version dropdown with 0 or 1 item. If we build
+  // the site with a single docs version (onlyIncludeVersions: ['1.0.0']),
+  // We'd rather render a button instead of a dropdown
+
+  if (items.length <= 1) {
+    return (
+      <DefaultNavbarItem
+        {...props}
+        mobile={mobile}
+        label={dropdownLabel}
+        to={dropdownTo}
+        isActive={dropdownActiveClassDisabled ? () => false : undefined}
+      />
+    );
+  }
+
+  return (
+    <DropdownNavbarItem
+      {...props}
+      mobile={mobile}
+      label={dropdownLabel}
+      to={dropdownTo}
+      items={items}
+      isActive={dropdownActiveClassDisabled ? () => false : undefined}
+    />
+  );
+}