From 97782ab6f500aecc16786a91d3a7a1c606f3995f Mon Sep 17 00:00:00 2001
From: Andrew Nicols <andrew@nicols.co.uk>
Date: Sun, 22 Dec 2024 22:40:54 +0800
Subject: [PATCH] [repo] Show a warning for stable versions that newer docs are
 available.

---
 nextVersion.js                              |  2 +
 src/theme/MoodlePageBanner/index.js         |  1 +
 src/theme/UnsupportedVersionBanner/index.js | 84 +++++++++++++++++++--
 3 files changed, 81 insertions(+), 6 deletions(-)

diff --git a/nextVersion.js b/nextVersion.js
index 3cf1b88c12..17f0eb2c0e 100644
--- a/nextVersion.js
+++ b/nextVersion.js
@@ -15,11 +15,13 @@
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+const latestVersion = '4.5';
 const nextVersion = '5.0';
 const nextLTSVersion = '5.3';
 const nextVersionRoot = `/docs/${nextVersion}`;
 
 module.exports = {
+    latestVersion,
     nextVersion,
     nextLTSVersion,
     nextVersionRoot,
diff --git a/src/theme/MoodlePageBanner/index.js b/src/theme/MoodlePageBanner/index.js
index 766abdeb03..ffc0d19549 100644
--- a/src/theme/MoodlePageBanner/index.js
+++ b/src/theme/MoodlePageBanner/index.js
@@ -28,6 +28,7 @@ export default function MoodlePageBanner({ frontMatter, metadata = {} }) {
             />
             <UnsupportedVersionBanner
                 frontMatter={frontMatter}
+                metadata={metadata}
             />
         </>
     );
diff --git a/src/theme/UnsupportedVersionBanner/index.js b/src/theme/UnsupportedVersionBanner/index.js
index 4a46ec6d8c..84b7b03d5a 100644
--- a/src/theme/UnsupportedVersionBanner/index.js
+++ b/src/theme/UnsupportedVersionBanner/index.js
@@ -21,6 +21,12 @@ import Translate from '@docusaurus/Translate';
 import AutoFixHighIcon from '@mui/icons-material/AutoFixHigh';
 import Admonition from '@theme/Admonition';
 import { getReleaseStatus, getVersion } from '@site/src/utils/SupportedReleases';
+import {
+    useActivePlugin,
+    useDocVersionSuggestions,
+} from '@docusaurus/plugin-content-docs/client';
+
+const getVersionMainDoc = (version) => version.docs.find((doc) => doc.id === version.mainDocId);
 
 function UnsupportedTitle() {
     return (
@@ -93,6 +99,34 @@ function GeneralSupportExpiredWarning({ versionData }) {
     );
 }
 
+function NewerVersionAvailableWarning({ versionData }) {
+    const { pluginId } = useActivePlugin({ failfast: true });
+    const { latestDocSuggestion, latestVersionSuggestion } = useDocVersionSuggestions(pluginId);
+    const latestVersionSuggestedDoc = latestDocSuggestion ?? getVersionMainDoc(latestVersionSuggestion);
+
+    return (
+        <Admonition
+            type="caution"
+            icon={
+                <AutoFixHighIcon fontSize="inherit" />
+            }
+            title="Newer Version Available"
+        >
+            <strong>
+                This documentation is for Moodle
+                {' '}
+                {versionData.name}
+                .
+            </strong>
+            <br />
+            You may also want to read the documentation for the
+            {' '}
+            <Link to={latestVersionSuggestedDoc.path}>upcoming version of Moodle</Link>
+            .
+        </Admonition>
+    );
+}
+
 function FutureReleaseWarning({ versionData }) {
     return (
         <Admonition
@@ -162,23 +196,45 @@ function ExperimentalWarning() {
     );
 }
 
-function VersionedSupportWarning({ versionData, moodleVersion }) {
+function VersionedSupportWarning({ versionData, moodleVersion, metadata }) {
     const releaseStatus = getReleaseStatus(versionData, moodleVersion);
+    const { sidebar } = metadata;
+
+    // Versions fit the following categories:
+    // - Experimental (show danger warning)
+    // - Current version (released or `main` branch)
+    //   - main branch (no warning)
+    //   - stable version information (no warning)
+    //   - stable versioned docs (indicate main branch information is available)
+    // - Security Only (show warning)
+    // - Future (show warning)
+    // - Future Stable (show warning)
+    // - Unsupported (show danger warning)
 
     if (versionData.isExperimental) {
-        // Experimental version.
+        // Experimental versions trump all.
+        // Always show this notice.
         return (
             <ExperimentalWarning versionData={versionData} />
         );
     }
 
+    if (sidebar === 'docs' && moodleVersion.version !== 'current' && metadata.slug !== '/') {
+        // This is a versioned doc page but it's not the 'current' version (main branch).
+        // Show a warning banner that that there are docs for the 'main' branch.
+        return (
+            <NewerVersionAvailableWarning versionData={versionData} />
+        );
+    }
+
     if (releaseStatus === 'current') {
-        // Still in general support.
+        // This documentation is for docs still in general support.
         return null;
     }
 
     if (releaseStatus === 'future' || releaseStatus === 'future-stable') {
-        // Not yet supported.
+        // This documentatino relates to a versino of Moodle which has yet to be released.
+        // This is probably a version about to be released.
         // TODO Add a warning banner.
         return (
             <FutureReleaseWarning versionData={versionData} />
@@ -197,8 +253,21 @@ function VersionedSupportWarning({ versionData, moodleVersion }) {
     );
 }
 
-export default function VersionInfo({ frontMatter }) {
-    const { moodleVersion = null } = frontMatter;
+const guessMoodleVersion = (frontMatter, metadata) => {
+    if (frontMatter.moodleVersion) {
+        return frontMatter.moodleVersion;
+    }
+
+    if (metadata.version) {
+        if (metadata.version.match(/^(?<seriesMajor>\d+\.\d+)(?<minor>\.\d+)?/)) {
+            return metadata.version;
+        }
+    }
+    return undefined;
+};
+
+export default function VersionInfo({ frontMatter, metadata = {} }) {
+    const moodleVersion = guessMoodleVersion(frontMatter, metadata);
 
     if (!moodleVersion) {
         // No version number found.
@@ -208,6 +277,7 @@ export default function VersionInfo({ frontMatter }) {
     const versionData = getVersion(moodleVersion);
     if (!versionData) {
         // No valid version data found.
+        // We don't know how to handle this version.
         return null;
     }
 
@@ -215,6 +285,8 @@ export default function VersionInfo({ frontMatter }) {
         <VersionedSupportWarning
             versionData={versionData}
             moodleVersion={moodleVersion}
+            metadata={metadata}
+            sidebar={metadata?.sidebar}
         />
     );
 }