Merge pull request #1638 from sunilarjun/2.5-banner

Updating Banner Field - Archive Documentation

docusaurus.config.js

@@ -209,7 +209,8 @@ module.exports = {
             },
             2.5: {
               label: 'v2.5',
-              path: 'v2.5'
+              path: 'v2.5',
+              className: 'toArchive' // Field used to denote documentation archival
             },
             '2.0-2.4': {
               label: 'v2.0-v2.4 (Archived)',

i18n/zh/code.json

@@ -1,4 +1,8 @@
 {
+  "theme.docs.versions.unmaintainedArchivedVersionLabel": {
+    "message": "This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained and is scheduled to be archived.",
+    "description": "The label used to tell the user that he's browsing an unmaintained doc version"
+  },
   "theme.ErrorPageContent.title": {
     "message": "页面已崩溃。",
     "description": "The title of the fallback page when the page crashed"

src/theme/DocVersionBanner/index.js

@@ -0,0 +1,143 @@
+import React from 'react';
+import clsx from 'clsx';
+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} from '@docusaurus/theme-common';
+import {
+  useDocsPreferredVersion,
+  useDocsVersion,
+} from '@docusaurus/theme-common/internal';
+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}) {
+  // Start of custom unmaintained archived version label. The purpose of this custom addition is to display a banner for docs versions that are scheduled for archiving.
+  if (versionMetadata.className === "toArchive") {
+    return (
+      <Translate
+        id="theme.docs.versions.unmaintainedArchivedVersionLabel"
+        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 and is scheduled to be archived."
+          }
+      </Translate>
+    );
+  } else {
+    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>,
+        }}>
+          {
+            "HELLO THERE This is documentation for {siteTitle} {versionLabel}, which is no longer actively maintained."
+          }
+      </Translate>
+    );
+  }
+  // End of custom unmaintained archived version label.
+}
+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), falling
+  // back 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;
+}