[docs] Lint all mdx files

MDX files are a subset of Markdown with JSX.

As such there is necessarily inline HTML present in the document.

.lintstagedrc.json

@@ -1,6 +1,10 @@
 {
   "*.css": ["stylelint --allow-empty-input --fix"],
   "*.{js,jsx,ts,tsx,mjs}": ["eslint --fix"],
+  "*.mdx": [
+    "markdownlint-cli2-config .markdownlint/mdx/fix/.markdownlint-cli2.cjs",
+    "cspell --no-must-find-files --no-progress"
+  ],
   "*.md": [
     "markdownlint-cli2-fix",
     "cspell --no-must-find-files --no-progress"

.markdownlint/mdx/.markdownlint-cli2.cjs

@@ -0,0 +1,29 @@
+/**
+ * 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/>.
+ */
+
+// For full details on all of these configuration settings:
+// https://github.com/DavidAnson/markdownlint#rules--aliases
+
+const config = require('../../.markdownlint-cli2.cjs');
+
+// MD033/no-inline-html - Inline HTML
+config.config.MD033 = false;
+
+// MD038/no-space-in-code Spaces inside code span elements
+config.config.MD038 = false;
+
+module.exports = config;

.markdownlint/mdx/fix/.markdownlint-cli2.cjs

@@ -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/>.
+ */
+
+// For full details on all of these configuration settings:
+// https://github.com/DavidAnson/markdownlint#rules--aliases
+
+const config = require('../.markdownlint-cli2.cjs');
+
+// Apply the fix.
+config.fix = true;
+
+module.exports = config;

docs/apis/_files/amd-dir.mdx

@@ -1,6 +1,7 @@
+<!-- markdownlint-disable first-line-heading -->
 JavaScript in Moodle is written in the ESM format, and transpiled into AMD modules for deployment.
 
-The [Moodle JavaScript Guide](../guides/javascript) has detailed information and examples on writing JavaScript in Moodle. Further information is also available in the [[Javascript Modules]] documentation.
+The [Moodle JavaScript Guide](../guides/javascript) has detailed information and examples on writing JavaScript in Moodle. Further information is also available in the [Javascript Modules](https://docs.moodle.org/dev/Javascript_Modules) documentation.
 
 :::caution
 

docs/apis/_files/backup-dir.mdx

@@ -1,6 +1,7 @@
+<!-- markdownlint-disable first-line-heading -->
 If your plugin stores data then you may need to implement the Backup feature which allows the activity to backed up, restored, and duplicated.
 
 For more information on Backup and restore, see the following:
 
-- [[Backup_2.0_for_developers]]
-- [[Restore_2.0_for_developers]]
+- [Backup 2.0 for developers](https://docs.moodle.org/dev/Backup_2.0_for_developers)
+- [Restore 2.0 for developers](https://docs.moodle.org/dev/Restore_2.0_for_developers)

docs/apis/_files/changes.mdx

@@ -1,4 +1,5 @@
-If your plugin includes a changelog in its root directory, this will be used to automatically pre-fill the release notes field when uploading new versions of your plugin to the [[Plugins directory]]. This file can be in any of the following locations:
+<!-- markdownlint-disable first-line-heading -->
+If your plugin includes a changelog in its root directory, this will be used to automatically pre-fill the release notes field when uploading new versions of your plugin to the [Plugins directory](https://docs.moodle.org/dev/Plugins_directory). This file can be in any of the following locations:
 
 - `CHANGES.md`: as a markdown file; or
 - `CHANGES.txt`: as a text file; or

docs/apis/_files/classes-dir.mdx

@@ -1,8 +1,9 @@
+<!-- markdownlint-disable first-line-heading -->
 Moodle supports, and recommends, the use of autoloaded PHP classes.
 
 By placing files within the `classes` directory or appropriate sub-directories, and with the correct PHP Namespace, and class name, Moodle is able to autoload classes without the need to manually require, or include them.
 
 Details on these rules and conventions are available in the following documentation:
 
 - [Coding style - namespace conventions](/general/development/policies/codingstyle#namespaces)
-- [[Automatic class loading]]
+- [Automatic class loading](https://docs.moodle.org/dev/Automatic_class_loading)

docs/apis/_files/cli-dir.mdx

@@ -1,4 +1,5 @@
-For plugins which make use of [[CLI scripts]], the convention is that these are placed into the `cli` folder to make their purpose clear, and easy to find.
+<!-- markdownlint-disable first-line-heading -->
+For plugins which make use of [CLI scripts](https://docs.moodle.org/dev/CLI_scripts), the convention is that these are placed into the `cli` folder to make their purpose clear, and easy to find.
 
 :::caution
 

docs/apis/_files/db-access-php.mdx

@@ -1,10 +1,12 @@
+<!-- markdownlint-disable first-line-heading -->
+
 The `db/access.php` file contains the __initial__ configuration for a plugin's access control rules.
 
 Access control is handled in Moodle by the use of Roles, and Capabilities. You can read more about these in the [Access API](../subsystems/access.md) documentation.
 
 :::caution Changing initial configuration
 
-If you make changes to the initial configuration of _existing_ access control rules, these will only take effect for _new installations of your plugin_. Any existing installation **will not** be updated with the latest configuraiton.
+If you make changes to the initial configuration of _existing_ access control rules, these will only take effect for _new installations of your plugin_. Any existing installation **will not** be updated with the latest configuration.
 
 Updating existing capability configuration for an installed site is not recommended as it may have already been modified by an administrator.
 

docs/apis/_files/db-events-php.mdx

@@ -1,4 +1,5 @@
-Moodle supports a feature known as _ [[Events_API#Event_observers|Event observers]] _ to allow components to make changes when certain events take place.
+<!-- markdownlint-disable first-line-heading -->
+Moodle supports a feature known as _ [Event observers](https://docs.moodle.org/dev/Events_API#Event_observers) _ to allow components to make changes when certain events take place.
 
 The `db/events.php` file allows you define any event subscriptions that your plugin needs to listen for.
 

docs/apis/_files/db-install-php.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 The `db/install.php` file allows you define a post-installation hook, which is called immediately after the initial creation of your database schema.
 
 :::caution

docs/apis/_files/db-install-xml.mdx

@@ -1,7 +1,8 @@
-The `install.xml` file is used to define any database tables, fields, indexes, and keys, which should be created for a plugin during its initial insatllation.
+<!-- markdownlint-disable first-line-heading -->
+The `install.xml` file is used to define any database tables, fields, indexes, and keys, which should be created for a plugin during its initial installation.
 
 :::caution
 
-When creating or updating the `install.xml` you **must** use the built-in [[XMLDB Documentation|XMLDB editor]] within Moodle.
+When creating or updating the `install.xml` you **must** use the built-in [XMLDB editor](https://docs.moodle.org/dev/XMLDB_Documentation) within Moodle.
 
-:::
+:::

docs/apis/_files/db-messages-php.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 The `db/messages.php` file allows you to declare the messages that your plugin sends.
 
-See the [[Message API]] documentation for further information.
+See the [Message API](https://docs.moodle.org/dev/Message_API) documentation for further information.

docs/apis/_files/db-mobile-php.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 The Moodle Mobile remote add-on is the mobile app version of the plugin that will be loaded when a user accesses the plugin on the app.
 
 A plugin can include several Mobile add-ons. Each add-on must indicate a unique name.

docs/apis/_files/db-renamedclasses-php.mdx

@@ -1 +1,2 @@
+<!-- markdownlint-disable first-line-heading -->
 Details of classes that have been renamed to fit in with autoloading. See [forum discussion](https://moodle.org/mod/forum/discuss.php?d=262403) for details.

docs/apis/_files/db-services-php.mdx

@@ -1,14 +1,15 @@
+<!-- markdownlint-disable first-line-heading -->
 The `db/services.php` file is used to describe the external functions available for use in web services. This includes
-web service functions defined for javascript, and for the [[Moodle Mobile App]].
+web service functions defined for javascript, and for the [Moodle Mobile App](https://docs.moodle.org/dev/Moodle_Mobile_App).
 
 :::note
 
-Web services should be named following the [[Web_service_API_functions#Naming_convention|naming convention for web services]].
+Web services should be named following the [naming convention for web services](https://docs.moodle.org/dev/Web_service_API_functions#Naming_convention).
 
 :::
 
 For further information on external functions and web services, see:
 
-- [[Adding a web service to a plugin]]
-- [[Web services API]]
-- [[External functions API]]
+- [Adding a web service to a plugin](https://docs.moodle.org/dev/Adding_a_web_service_to_a_plugin)
+- [Web services API](https://docs.moodle.org/dev/Web_services_API)
+- [External functions API](https://docs.moodle.org/dev/External_functions_API)

docs/apis/_files/db-uninstall-php.mdx

@@ -1 +1,2 @@
+<!-- markdownlint-disable first-line-heading -->
 The `db/uninstall.php` file allows you define a pre-uninstallation hook, which is called immediately before all table and data from your plugin are removed.

docs/apis/_files/db-upgrade-php.mdx

@@ -1,10 +1,11 @@
+<!-- markdownlint-disable first-line-heading -->
 The `db/upgrade.php` file contains upgrade steps, including database schema changes, changes to settings, and other steps which must be performed during upgrade.
 
-See the [[Upgrade API]] documentation for further information.
+See the [Upgrade API](https://docs.moodle.org/dev/Upgrade_API) documentation for further information.
 
 :::danger Generating Database Schema changes
 
-When making changes to the database schema you **must** use the build-in [[XMLDB Documentation|XMDLB editor]] within
+When making changes to the database schema you **must** use the build-in [XMLDB editor](https://docs.moodle.org/dev/XMLDB_Documentation) within
 Moodle. This can be used to generate php upgrade steps.
 
 The [install.xml](#dbinstallxml) schema must match the schema generated by the upgrade at all times.
@@ -13,7 +14,7 @@ The [install.xml](#dbinstallxml) schema must match the schema generated by the u
 
 To create an upgrade step you must:
 
-1. Use the [[XMLDB_editor]] to create the definition of the new fields
+1. Use the [XMLDB editor](https://docs.moodle.org/dev/XMLDB_editor) to create the definition of the new fields
 1. Update the `install.xml` from the XMLDB editor
 1. Generate the PHP upgrade steps from within the XMLDB Editor
 1. Update the version number in your `version.php`
@@ -26,4 +27,4 @@ In many cases you will be able to combine multiple upgrade steps into a single v
 
 When a version number increment is detected during an upgrade, the `xmldb_[pluginname]_upgrade` function is called with the old version number as the first argument.
 
-See the [[Upgrade API]] documentation for more information on the upgrade process.
+See the [Upgrade API](https://docs.moodle.org/dev/Upgrade_API) documentation for more information on the upgrade process.

docs/apis/_files/environment-xml.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 A plugin can declare its own environment requirements, in addition to those declared by Moodle core. These may includes features such as PHP extension requirements, version requirements, and similar items.
 
-Further information on this file and its format can be found in the [[Environment checking]] documentation.
+Further information on this file and its format can be found in the [Environment checking](https://docs.moodle.org/dev/Environment_checking) documentation.

docs/apis/_files/lib.mdx

@@ -1,4 +1,6 @@
-The `lib.php` file is a legacy file which acts as a bridge between Moodle core, and the plugin. In recent plugins it is should only used to define callbacks and related functionality which currenltly is not supported as an autoloadable class.
+<!-- markdownlint-disable first-line-heading -->
+
+The `lib.php` file is a legacy file which acts as a bridge between Moodle core, and the plugin. In recent plugins it is should only used to define callbacks and related functionality which currently is not supported as an auto-loadable class.
 
 All functions defined in this file **must** meet the requirements set out in the relevant section of the [Coding style](/general/development/policies/codingstyle#Functions-and-Methods).
 

docs/apis/_files/locallib.mdx

@@ -1,3 +1,6 @@
+<!-- markdownlint-disable first-line-heading -->
+<!-- cspell:ignore locallib -->
+
 :::caution Legacy feature
 
 The use of this file is no longer recommended, and new uses of it will not be permitted in core code.

docs/apis/_files/pix-dir.mdx

@@ -1,5 +1,6 @@
+<!-- markdownlint-disable first-line-heading -->
 Plugins can provide icons in several formats, and most plugin types require that a default icon be provided.
 
 Where a browser supports it, the `svg` format is used, falling back to `png` formats when an SVG is unavailable.
 
-Full details of the correct naming, sizing, and design guidelines for icons in Moodle can be found in the [[Moodle icons]] documentation.
+Full details of the correct naming, sizing, and design guidelines for icons in Moodle can be found in the [Moodle icons](https://docs.moodle.org/dev/Moodle_icons) documentation.

docs/apis/_files/readme.mdx

@@ -1,3 +1,4 @@
-We recommend that you include any additional information for your plugin in a project readme file. Ideally this should act as an offline version of all information in your plugin's page in the [[Plugins directory]].
+<!-- markdownlint-disable first-line-heading -->
+We recommend that you include any additional information for your plugin in a project readme file. Ideally this should act as an offline version of all information in your plugin's page in the [Plugins directory](https://docs.moodle.org/dev/Plugins_directory).
 
 We recommend creating your readme file in either a `README.md`, or `README.txt` format.

docs/apis/_files/readme_moodle-txt.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 When importing a third-party library into your plugin, it is advisable to create a `readme_moodle.txt` file detailing relevant information, including:
 
 - Download URLs

docs/apis/_files/settings-php.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 You can define settings for your plugin that the administrator can configure by creating a `settings.php` file in the root of your plugins' directory.
 
 :::caution
@@ -12,4 +13,4 @@ By following the correct naming, all settings will automatically be stored in th
 
 :::
 
-Full details on how to create settings are available in the [[Admin settings]] documentation.
+Full details on how to create settings are available in the [Admin settings](https://docs.moodle.org/dev/Admin_settings) documentation.

docs/apis/_files/styles-css.mdx

@@ -1,7 +1,8 @@
+<!-- markdownlint-disable first-line-heading -->
 Plugins may define a '/styles.css' to provide plugin-specific styling. See the following for further documentation:
 
-- [[Plugin contribution checklist#CSS styles]]
-- [[CSS Coding Style]]
+- [Plugin contribution checklist#CSS styles](https://docs.moodle.org/dev/Plugin_contribution_checklist#CSS_styles)
+- [CSS Coding Style](https://docs.moodle.org/dev/CSS_Coding_Style)
 
 :::tip Avoid custom styles where possible
 

docs/apis/_files/thirdpartylibs-xml.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 Details of all third-party libraries should be declared in the `thirdpartylibs.xml` file.
 
 This information is used to generate ignore file configuration for linting tools. For Moodle core it is also used to generate library information as part of release notes and credits.
@@ -10,4 +11,4 @@ The license of any third-party code included in your plugin, and within the `thi
 
 :::
 
-See the [[Third_Party_Libraries]] documentation for further information.
+See the [Third Party Libraries](https://docs.moodle.org/dev/Third_Party_Libraries) documentation for further information.

docs/apis/_files/upgrade-php.mdx

@@ -1,10 +1,11 @@
+<!-- markdownlint-disable first-line-heading -->
 The `db/upgrade.php` file contains upgrade steps, including database schema changes, changes to settings, and other steps which must be performed during upgrade.
 
-See the [[Upgrade API]] documentation for further information.
+See the [Upgrade API](https://docs.moodle.org/dev/Upgrade_API) documentation for further information.
 
 :::danger Generating Database Schema changes
 
-When making changes to the database schema you **must** use the build-in [[XMLDB Documentation|XMDLB editor]] within
+When making changes to the database schema you **must** use the build-in [XMLDB editor](https://docs.moodle.org/dev/XMLDB_Documentation) within
 Moodle. This can be used to generate php upgrade steps.
 
 The [install.xml](#dbinstallxml) schema must match the schema generated by the upgrade at all times.

docs/apis/_files/version-php.mdx

@@ -1,3 +1,4 @@
+<!-- markdownlint-disable first-line-heading -->
 The version.php contains metadata about the plugin.
 
 It is used during the installation and upgrade of the plugin.

docs/apis/_files/yui-dir.mdx

@@ -1,10 +1,11 @@
-In older versions of Moodle, JavaScript was written in the YUI format. This is being phased out in favour of [[Javascript Modules]], although some older uses still remain in Moodle core.
+<!-- markdownlint-disable first-line-heading -->
+In older versions of Moodle, JavaScript was written in the YUI format. This is being phased out in favour of [Javascript Modules](https://docs.moodle.org/dev/Javascript_Modules), although some older uses still remain in Moodle core.
 
-- [[YUI/Modules]]
-- [[YUI]]
+- [YUI/Modules](https://docs.moodle.org/dev/YUI/Modules)
+- [YUI](https://docs.moodle.org/dev/YUI)
 
 :::caution
 
-New YUI code will not be accepted into Moodle core, except for new plugins for the [[Atto|Atto editor]].
+New YUI code will not be accepted into Moodle core, except for new plugins for the [Atto editor](https://docs.moodle.org/dev/Atto).
 
 :::

docs/apis/commonfiles/index.mdx

@@ -37,7 +37,7 @@ import {
 
 <!-- markdownlint-disable MD033/no-inline-html -->
 
-This page describes the common files which may be present in any Moodle subsystem or [[Plugin types|plugin type]]. Some of these files are mandatory and __must__ exist within a component, whilst others are optional.
+This page describes the common files which may be present in any Moodle subsystem or [plugin type](https://docs.moodle.org/dev/Plugin_types). Some of these files are mandatory and __must__ exist within a component, whilst others are optional.
 
 ### version.php
 
@@ -147,8 +147,8 @@ import extraLangDescription from '../_files/lang-extra.md';
 
 ## See also
 
-- [[Moodle architecture]] - general overview of Moodle code architecture
-- [[Plugin types]] - list of all supported plugin types
+- [Moodle architecture](https://docs.moodle.org/dev/Moodle_architecture) - general overview of Moodle code architecture
+- [Plugin types](https://docs.moodle.org/dev/Plugin_types) - list of all supported plugin types
 - [Moodle plugins directory](https://moodle.org/plugins/) - repository of contributed plugins for Moodle
 - [Moodle plugin skeleton generator](https://moodle.org/plugins/tool_pluginskel) - allows to quickly generate code skeleton for a new plugin
 - [Checklist for plugin contributors](https://docs.moodle.org/dev/Plugin_contribution_checklist) - read before submitting a plugin

docs/apis/plugintypes/antivirus/_files/scanner-php.mdx

@@ -1,3 +1,6 @@
+<!-- markdownlint-disable first-line-heading -->
+<!-- cspell:ignore deleteinfected -->
+
 The `classes/scanner.php` class must be defined in the correct namespace for your plugin, and must extend the `\core\antivirus\scanner` class.
 
 It is responsible for implementing the interface between Moodle and the antivirus scanning tool.