[repo] Add markdownlint rule to replace migrated links

.markdownlint/fix-migrated-links.js

@@ -0,0 +1,88 @@
+/**
+ * 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/>.
+ */
+
+/* eslint-disable import/no-extraneous-dependencies */
+
+const {
+    addError,
+    forEachLine,
+    getLineMetadata,
+} = require('markdownlint-rule-helpers');
+
+const { isMigrated, getMigrationLink } = require('../migratedPages');
+
+// eslint-disable-next-line max-len
+const linkFinder = /(?<description>\[.*\](?=(?<link>\(https:\/\/docs.moodle.org\/dev\/(?<target>[^)]*)\)|\[[^\]]*\])))/g;
+
+module.exports = {
+    names: ['MDLDOC003', 'fix-legacylinks'],
+    description: 'Find and replace links to any migrated docs',
+    tags: ['migration'],
+    function: function MDLDOC003(params, onError) {
+        forEachLine(getLineMetadata(params), (line, lineIndex, inCode) => {
+            if (inCode) {
+                // Do not make changes to code stanzas.
+                return;
+            }
+
+            const lineNumber = lineIndex + 1;
+            let matches = linkFinder.exec(line);
+            if (!matches) {
+                return;
+            }
+            do {
+                const { target } = matches.groups;
+                if (!target) {
+                    return;
+                }
+                const [targetPage, bookmark] = target.split('#');
+                const context = `${matches.groups.description}${matches.groups.link}`;
+
+                if (isMigrated(targetPage)) {
+                    const column = matches.index;
+                    const getReplacementValue = () => {
+                        const link = getMigrationLink(targetPage, params.name);
+                        if (bookmark) {
+                            const migratedBookmark = bookmark
+                                .replaceAll('_', '-')
+                                .toLowerCase();
+                            return `${link}#${migratedBookmark}`;
+                        }
+
+                        return link;
+                    };
+                    const fixInfo = {
+                        editColumn: column + 1,
+                        deleteCount: context.length,
+                        insertText: `${matches.groups.description}(${getReplacementValue()})`,
+                    };
+
+                    addError(
+                        onError,
+                        lineNumber,
+                        target,
+                        context,
+                        [matches.index + 1, context.length],
+                        fixInfo,
+                    );
+                }
+
+                matches = linkFinder.exec(line);
+            } while (matches !== null);
+        });
+    },
+};

.vscode/settings.json

@@ -1,6 +1,7 @@
 {
     "markdownlint.customRules": [
-        "./.markdownlint/no-directional-quotation-marks"
+        "./.markdownlint/no-directional-quotation-marks",
+        "./.markdownlint/fix-migrated-links"
     ],
     "stylelint.packageManager": "yarn"
 }

docusaurus.config.js

@@ -15,6 +15,7 @@
  * along with Moodle.  If not, see <http://www.gnu.org/licenses/>.
  */
 
+/* eslint-disable global-require */
 require('dotenv').config();
 
 const Versions = require('./versions.json');
@@ -31,14 +32,14 @@ versionConfig.current = {
 // Share the remarkPlugins between all presets.
 const remarkPlugins = [
     require('./src/remark/trackerLinks'),
-    require('./src/remark/legacyDocLinks'),
     require('mdx-mermaid'),
 ];
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
     title: 'Moodle',
     tagline: '(Un)official Developer Resources',
+    // eslint-disable-next-line spaced-comment
     //url: 'https://develop.moodle.org',
     url: process.env?.url || 'https://moodle.github.io',
     baseUrl: process.env?.baseUrl || '/devdocs/',

migratedPages.js

@@ -24,7 +24,10 @@ const obsoleteDocs = require('./data/obsoletePages.json');
  * A list of documents which have been migrated with their source and destination paths shown.
  */
 /* eslint-disable-next-line no-restricted-properties */
-const migratedDocs = yaml.load(fs.readFileSync('./data/migratedPages.yml', 'utf8'));
+const migratedDocs = yaml.load(fs.readFileSync(path.join(
+    __dirname,
+    'data/migratedPages.yml',
+), 'utf8'));
 
 const isObsolete = (legacyPath) => obsoleteDocs.indexOf(legacyPath) !== -1;
 
@@ -85,29 +88,31 @@ const getMigrationLink = (legacyPath, usedIn) => {
 
     const replacementIsGeneral = replacementFile.startsWith('general/');
     const usedInIsGeneral = relativeUsedIn.startsWith('general/');
-    const bothGeneral = replacementIsGeneral && usedInIsGeneral;
-    const neitherGeneral = !replacementIsGeneral && !usedInIsGeneral;
 
-    if (bothGeneral || neitherGeneral) {
-        const absRelativeUsedIn = getAbsoluteDirectory(relativeUsedIn);
-        const absReplacementFile = path.join(process.env.PWD, replacementFile);
-        const relativeLink = path.relative(absRelativeUsedIn, absReplacementFile);
+    const normaliseReplacement = (file) => {
+        if (file.endsWith('index.md')) {
+            return `/${file.replace(/\/index\.md$/, '')}`;
+        }
 
-        if (relativeLink.startsWith('.')) {
-            return relativeLink;
+        if (file.endsWith('.md')) {
+            return `/${file.replace(/\.md$/, '')}`;
         }
-        return `./${relativeLink}`;
-    }
 
-    if (replacementFile.endsWith('index.md')) {
-        return `/${replacementFile.replace(/\/index\.md$/, '')}`;
-    }
+        return `/${file}`;
+    };
 
-    if (replacementFile.endsWith('.md')) {
-        return `/${replacementFile.replace(/\.md$/, '')}`;
+    if (replacementIsGeneral || usedInIsGeneral) {
+        return normaliseReplacement(`${replacementFile}`);
     }
 
-    return `/${replacementFile}`;
+    const absRelativeUsedIn = getAbsoluteDirectory(relativeUsedIn);
+    const absReplacementFile = path.join(__dirname, replacementFile);
+    const relativeLink = path.relative(absRelativeUsedIn, absReplacementFile);
+
+    if (relativeLink.startsWith('.')) {
+        return relativeLink;
+    }
+    return `./${relativeLink}`;
 };
 
 module.exports = {

package.json

@@ -15,7 +15,7 @@
     "wikimedia-sync": "scripts/wikimedia-sync.js",
     "component-spellings": "scripts/component-helper.js spelling",
     "test": "jest",
-    "mdlint-doc": "markdownlint --rules .markdownlint/no-directional-quotation-marks --rules .markdownlint/no-wikilinks ",
+    "mdlint-doc": "markdownlint --rules .markdownlint/no-directional-quotation-marks --rules .markdownlint/no-wikilinks --rules .markdownlint/fix-migrated-links",
     "mdlint-all": "yarn mdlint-doc '{docs,general}/**/*.md' '*.md'",
     "lint": "yarn mdlint-all",
     "prepare": "husky install",