[repo] Adjust /docs to include next version

This commit changes the unversioned docs at /docs/ to instead be at
/docs/[nextVersionNumber].

It includes a redirect for /docs/* (where an existing page is not found)
and it adds helpers to specify the version number in URLs and other
locations.

Fixes moodle#955

config/navbar.js

@@ -15,6 +15,7 @@
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
 const VersionsArchived = require('../versionsArchived.json');
+const nextVersionData = require('../nextVersion.js');
 
 const ArchivedVersionsDropdownItems = Object.entries(VersionsArchived).splice(
     0,
@@ -31,7 +32,7 @@ const navbar = {
     },
     items: [
         {
-            to: '/docs',
+            to: nextVersionData.nextVersionRoot,
             label: 'Guides',
             position: 'left',
         },

docusaurus.config.js

@@ -19,6 +19,9 @@ import { config as dotEnvConfig } from 'dotenv';
 import Versions from './versions.json';
 import MoodleBannerRemark from './src/remark/moodleBanner.js';
 import TrackerLinksRemark from './src/remark/trackerLinks.js';
+import UnversionedDocsLinksRemark from './src/remark/unversionedDocsLinks.js';
+
+// eslint-disable global-require
 
 dotEnvConfig();
 
@@ -29,29 +32,25 @@ const versionConfig = Object.fromEntries(Versions.map((version) => [version, {
 versionConfig.current = {
     label: 'main',
     banner: 'none',
+    path: '4.4',
 };
 
 // Share the remarkPlugins between all presets.
 const remarkPlugins = [
     MoodleBannerRemark,
     TrackerLinksRemark,
+    UnversionedDocsLinksRemark,
 ];
 
 const isDeployPreview = !!process.env.NETLIFY && process.env.CONTEXT === 'deploy-preview';
 
 const getBaseUrl = () => {
-    if (process.env.NETLIFY) {
-        // Netlify hosts on '/', always.
-        return '/';
-    }
-
     if (typeof process.env.BASEURL !== 'undefined') {
         // Respect the env.
         return process.env.BASEURL;
     }
 
-    // Default is currently '/devdocs'.
-    return '/devdocs/';
+    return '/';
 };
 
 /** @type {import('@docusaurus/types').Config} */

nextVersion.js

@@ -0,0 +1,26 @@
+/**
+ * Copyright (c) Moodle Pty Ltd.
+ *
+ * Moodle is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Moodle is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+const nextVersion = '4.4';
+const nextLTSVersion = '4.5';
+const nextVersionRoot = `/docs/${nextVersion}`;
+
+module.exports = {
+    nextVersion,
+    nextLTSVersion,
+    nextVersionRoot,
+};

src/components/HomepageFeatures/index.js

@@ -19,6 +19,7 @@ import React from 'react';
 import clsx from 'clsx';
 import styles from './styles.module.css';
 import Link from '@docusaurus/Link';
+import NextVersionData from '@site/nextVersion';
 
 /* eslint-disable global-require */
 
@@ -48,7 +49,7 @@ const FeatureList = [
         linkText: 'View standards',
     },
     {
-        link: '/docs/apis',
+        link: `${NextVersionData.nextVersionRoot}/apis`,
         title: 'API guides',
         Svg: require('@site/static/img/undraw_docusaurus_react.svg').default,
         description: (

src/remark/unversionedDocsLinks.js

@@ -0,0 +1,58 @@
+/**
+ * Copyright (c) Moodle Pty Ltd.
+ *
+ * Moodle is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Moodle is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
+import { SKIP, CONTINUE, visit } from 'unist-util-visit';
+import { nextVersionRoot } from '../../nextVersion.js';
+
+/**
+ * Update any /docs/* link to point to /docs/:nextVersion.
+ *
+ * @param {Tree} node
+ * @param {Number} index
+ * @param {Tree} parent
+ * @returns {Number|String} The next index to process, or 'skip' to skip this node.
+ */
+const updateLink = (node) => {
+    if (!node.url) {
+        return SKIP;
+    }
+
+    if (!node.url.startsWith('/docs/')) {
+        return SKIP;
+    }
+
+    if (node.url.match(/\/docs\/\d\.\d/)) {
+        return SKIP;
+    }
+
+    // Get the current version.
+    node.url = node.url.replace(/^\/docs\//, `${nextVersionRoot}/`);
+
+    return CONTINUE;
+};
+
+const plugin = () => async (ast) => {
+    // Visit all nodes on the AST which are of type 'link' and apply the updateLink function on them.
+    // The visit function's third parameter is a Visitor function.
+    // See the docs at https://github.com/syntax-tree/unist-util-visit-parents
+    // Note: It has a mixed return type.
+    // - If the Visitor function returns 'skip', then the visit function will skip this node and continue.
+    // - If the Visitor function returns a Number, then the visit function will continue from that index.
+    visit(ast, 'link', (node, index, parent) => updateLink(node, index, parent));
+};
+
+export default plugin;

static/_redirects

@@ -59,3 +59,7 @@
 # Issue 415
 # Redirect /roadmap to /general/community/roadmap
 /roadmap/* /general/community/roadmap/:splat
+
+# Issue #955
+# Redirect /docs/* to /docs/4.4/:splat
+/docs/* /docs/4.4/:splat