moodle · andrewnicols · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026 · Apr 13, 2026
diff --git a/.yarn/releases/yarn-4.13.0.cjs b/.yarn/releases/yarn-4.13.0.cjs
diff --git a/.yarn/releases/yarn-4.9.2.cjs b/.yarn/releases/yarn-4.9.2.cjs
diff --git a/.yarnrc.yml b/.yarnrc.yml
@@ -4,4 +4,4 @@ enableGlobalCache: false
 
 nodeLinker: node-modules
 
-yarnPath: .yarn/releases/yarn-4.9.2.cjs
+yarnPath: .yarn/releases/yarn-4.13.0.cjs
diff --git a/README.md b/README.md
@@ -1,8 +1,8 @@
 # Moodle Developer Resources
 
 <p align="center">
-  <!--<a href="CONTRIBUTING.md#pull-requests"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>-->
-  <!--<a href="#license"><img src="https://img.shields.io/github/license/sourcerer-io/hall-of-fame.svg?colorB=ff0000"></a>-->
+  {/* <!--<a href="CONTRIBUTING.md#pull-requests"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome"></a>--> */}
+  {/* <!--<a href="#license"><img src="https://img.shields.io/github/license/sourcerer-io/hall-of-fame.svg?colorB=ff0000"></a>--> */}
   <a href="https://gitpod.io/#https://github.com/moodle/devdocs"><img src="https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod" alt="Gitpod Ready-to-Code"/></a>
   <a href="https://meercode.io/moodle/devdocs"><img src="https://meercode.io/badge/moodle/devdocs?type=ci-score" alt="CI Score"></a>
   <a href="https://github.com/moodle/devdocs/actions/workflows/markdown-lint.yml"><img src="https://github.com/moodle/devdocs/actions/workflows/markdown-lint.yml/badge.svg" alt="Lint status"></a>

diff --git a/cspell.config.js b/cspell.config.js
@@ -92,6 +92,9 @@ const config = {
 
         // Ignore relative paths in markdown links.
         '/\\]([^)]*)/gm',
+
+        // Ignore mdx comments in the format {/* COMMENT */}.
+        '/\\{\\/\\*[\\s\\S]*?\\*\\/\\}/g',
     ],
 };
 

diff --git a/docs/apis.md b/docs/apis.md
diff --git a/docs/apis/_files/amd-dir.mdx b/docs/apis/_files/amd-dir.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](../../guides/javascript/modules.md) documentation.

diff --git a/docs/apis/_files/backup-dir.mdx b/docs/apis/_files/backup-dir.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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:

diff --git a/docs/apis/_files/changes.mdx b/docs/apis/_files/changes.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](/general/community/plugincontribution/pluginsdirectory). This file can be in any of the following locations:
 
 - `CHANGES.md`: as a markdown file; or

diff --git a/docs/apis/_files/classes-dir.mdx b/docs/apis/_files/classes-dir.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.

diff --git a/docs/apis/_files/cli-dir.mdx b/docs/apis/_files/cli-dir.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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

diff --git a/docs/apis/_files/composer-json.mdx b/docs/apis/_files/composer-json.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
 The `composer.json` file allows your plugin to be distributed and installed via [Composer](https://getcomposer.org/).
 
 Moodle uses the [moodle/composer-installer](https://github.com/moodle/composer-installer) package to install Moodle plugins from Composer into the correct locations within the Moodle directory structure.

diff --git a/docs/apis/_files/db-access-php.mdx b/docs/apis/_files/db-access-php.mdx
@@ -1,10 +1,10 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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
+:::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 configuration.
 

diff --git a/docs/apis/_files/db-events-php.mdx b/docs/apis/_files/db-events-php.mdx
@@ -1,11 +1,11 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.
 
 Event subscriptions are a convenient way to observe events generated elsewhere in Moodle.
 
-:::caution Communication between components
+:::caution[Communication between components]
 
 You _should not_ use event subscriptions to subscribe to events belonging to other plugins, without defining a dependency upon that plugin.
 

diff --git a/docs/apis/_files/db-install-php.mdx b/docs/apis/_files/db-install-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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

diff --git a/docs/apis/_files/db-install-xml.mdx b/docs/apis/_files/db-install-xml.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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

diff --git a/docs/apis/_files/db-legacyclasses-php.mdx b/docs/apis/_files/db-legacyclasses-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
 Details of legacy classes that have been moved to the classes directory to support autoloading but are not yet named properly.
 
 :::note

diff --git a/docs/apis/_files/db-messages-php.mdx b/docs/apis/_files/db-messages-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
 The `db/messages.php` file allows you to declare the messages that your plugin sends.
 
 See the [Message API](../core/message/index.md) documentation for further information.
diff --git a/docs/apis/_files/db-mobile-php.mdx b/docs/apis/_files/db-mobile-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.

diff --git a/docs/apis/_files/db-renamedclasses-php.mdx b/docs/apis/_files/db-renamedclasses-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.
 
 :::note

diff --git a/docs/apis/_files/db-services-php.mdx b/docs/apis/_files/db-services-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](/general/app).

diff --git a/docs/apis/_files/db-tasks-php.mdx b/docs/apis/_files/db-tasks-php.mdx
@@ -1,8 +1,8 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
 
 The `db/tasks.php` file contains the initial schedule configuration for each of your plugins _scheduled_ tasks. Adhoc tasks are not run on a regular schedule and therefore are not described in this file.
 
-:::caution Editing the schedule for an existing task
+:::caution[Editing the schedule for an existing task]
 
 If an existing task is edited, it will only be updated in the database if the administrator has not customised the schedule of that task in any way.
 

diff --git a/docs/apis/_files/db-uninstall-php.mdx b/docs/apis/_files/db-uninstall-php.mdx
@@ -1,2 +1,2 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.
diff --git a/docs/apis/_files/db-upgrade-php.mdx b/docs/apis/_files/db-upgrade-php.mdx
@@ -1,9 +1,9 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](../../guides/upgrade/index.md) documentation for further information.
 
-:::danger Generating Database Schema changes
+:::danger[Generating Database Schema changes]
 
 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.

diff --git a/docs/apis/_files/environment-xml.mdx b/docs/apis/_files/environment-xml.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](https://docs.moodle.org/dev/Environment_checking) documentation.
diff --git a/docs/apis/_files/lang-extra.md b/docs/apis/_files/lang-extra.md
@@ -1,6 +1,6 @@
-<!-- markdownlint-disable MD041 -->
+{/* <!-- markdownlint-disable MD041 --> */}
 
-:::caution Activity modules are different
+:::caution[Activity modules are different]
 
 Activity modules do not use the __frankenstyle__ name as a filename, they use the plugin name. For example the forum activity plugin:
 

diff --git a/docs/apis/_files/lang.md b/docs/apis/_files/lang.md
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable MD041 -->
+{/* <!-- markdownlint-disable MD041 --> */}
 
 Each plugin must define a set of language strings with, at a minimum, an English translation. These are specified in the plugin's `lang/en` directory in a file named after the plugin. For example the LDAP authentication plugin:
 

diff --git a/docs/apis/_files/lib.mdx b/docs/apis/_files/lib.mdx
@@ -1,10 +1,10 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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).
 
-:::note Performance impact
+:::note[Performance impact]
 
 Moodle core often loads all the <tt>lib.php</tt> files of a given plugin types. For performance reasons, it is strongly recommended to keep this file as small as possible and have just required code implemented in it. All the plugin's internal logic should be implemented in the auto-loaded classes.
 

diff --git a/docs/apis/_files/locallib.mdx b/docs/apis/_files/locallib.mdx
@@ -1,7 +1,7 @@
-<!-- markdownlint-disable first-line-heading -->
-<!-- cspell:ignore locallib -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
+{/* <!-- cspell:ignore locallib --> */}
 
-:::caution Legacy feature
+:::caution[Legacy feature]
 
 The use of this file is no longer recommended, and new uses of it will not be permitted in core code.
 

diff --git a/docs/apis/_files/pix-dir.mdx b/docs/apis/_files/pix-dir.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.

diff --git a/docs/apis/_files/readme.mdx b/docs/apis/_files/readme.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](/general/community/plugincontribution/pluginsdirectory).
 
 We recommend creating your readme file in either a `README.md`, or `README.txt` format.
diff --git a/docs/apis/_files/readme_moodle-txt.mdx b/docs/apis/_files/readme_moodle-txt.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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

diff --git a/docs/apis/_files/settings-php.mdx b/docs/apis/_files/settings-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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

diff --git a/docs/apis/_files/styles-css.mdx b/docs/apis/_files/styles-css.mdx
@@ -1,10 +1,10 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](/general/community/plugincontribution/checklist#css-styles)
 - [CSS Coding Style](https://docs.moodle.org/dev/CSS_Coding_Style)
 
-:::tip Avoid custom styles where possible
+:::tip[Avoid custom styles where possible]
 
 Rather than writing custom CSS for your plugin, where possible apply Bootstrap classes to the DOM elements in your output. These will be easier to maintain and will adopt most colour, branding, and other customisations applied to a theme.
 

diff --git a/docs/apis/_files/thirdpartylibs-xml.mdx b/docs/apis/_files/thirdpartylibs-xml.mdx
@@ -1,11 +1,11 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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.
 
 Within the XML the `location` is a file, or directory, relative to your plugin's root.
 
-:::caution Licensing
+:::caution[Licensing]
 
 The license of any third-party code included in your plugin, and within the `thirdpartylibs.xml` file **must** be [compatible with the GNU GPLv3](http://www.gnu.org/licenses/license-list.html#GPLCompatibleLicenses).
 

diff --git a/docs/apis/_files/upgrade-php.mdx b/docs/apis/_files/upgrade-php.mdx
@@ -1,9 +1,9 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](../../guides/upgrade/index.md) documentation for further information.
 
-:::danger Generating Database Schema changes
+:::danger[Generating Database Schema changes]
 
 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.

diff --git a/docs/apis/_files/upgrade-txt.mdx b/docs/apis/_files/upgrade-txt.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
 Each component and subsystem may make use of an `upgrade.txt` file in the top level folder. A section title is used to identify the Moodle version where the change was introduced, and significant changes for that version relating to that component or subsystem are noted.
 
 For example, given an API change is applied for the upcoming Moodle version 4.1 which is still in the **main** branch (4.1dev), the version number on the `upgrade.txt`'s section title will be set to **4.1**.
@@ -8,7 +8,7 @@ For example, given an API change is applied for the upcoming Moodle version 4.1
 An API change to empower educators!
 ```
 
-#### Changes applied to multiple branches
+#### Changes applied to multiple branches {/* #changes-applied-to-multiple-branches */}
 
 When changes are integrated to multiple branches, for example a stable version and the main branch, then the relevant versions used to describe the change in the `upgrade.txt` file should be the next version to be released _for each branch_. The **main** branch should always use the next major version.
 
@@ -19,7 +19,7 @@ For example, if a change is applied to the **MOODLE_400_STABLE** during the deve
 An API change to empower educators!
 ```
 
-#### Mentioning other Moodle versions the change applies to
+#### Mentioning other Moodle versions the change applies to {/* #mentioning-other-moodle-versions-the-change-applies-to */}
 
 Multiple versions within the section title are **not** allowed. However, developers may note the Moodle versions that the change applies to within the upgrade note text itself.
 
@@ -38,7 +38,7 @@ An API change to empower educators! (This was fixed in 4.1 and 4.0.2)
 An API change to empower educators!
 ```
 
-#### Exception during parallel development
+#### Exception during parallel development {/* #exception-during-parallel-development */}
 
 When Moodle is developing two major versions in parallel, for example Moodle 3.11.0, and Moodle 4.0.0, then the
 version in the earliest of the major version development branches will be used for both branches.

diff --git a/docs/apis/_files/version-php.mdx b/docs/apis/_files/version-php.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- markdownlint-disable first-line-heading --> */}
 The version.php contains metadata about the plugin.
 
 It is used during the installation and upgrade of the plugin.

diff --git a/docs/apis/_files/yui-dir.mdx b/docs/apis/_files/yui-dir.mdx
@@ -1,4 +1,4 @@
-<!-- markdownlint-disable first-line-heading -->
+{/* <!-- 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](../../guides/javascript/modules.md), although some older uses still remain in Moodle core.
 
 - [YUI/Modules](../../guides/javascript/yui/modules.md)

diff --git a/docs/apis/commonfiles/db-tasks.php/index.md b/docs/apis/commonfiles/db-tasks.php/index.md
@@ -28,9 +28,9 @@ $tasks = [
 
 Each task configuration entry has a number of possible properties, described below.
 
-## Task configuration entries
+## Task configuration entries {/* #task-configuration-entries */}
 
-### Classname
+### Classname {/* #classname */}
 
 <LanguageProperty
     required
@@ -48,7 +48,7 @@ $tasks = [
 ]
 ```
 
-### Blocking
+### Blocking {/* #blocking */}
 
 <LanguageProperty
     types={["integer"]}
@@ -72,7 +72,7 @@ $tasks = [
 ];
 ```
 
-### Date and time fields
+### Date and time fields {/* #date-and-time-fields */}
 
 <LanguageProperty
     types={["string"]}
@@ -97,7 +97,7 @@ Each of these fields accepts one, or more values, and the format for each field
 <random>    := R
 ```
 
-:::info Random values
+:::info[Random values]
 
 A fixed random value can be selected by using a value of `R`. By specifying this option, a random day or time is chosen when the task is installed or updated. The same value will be used each time the task is scheduled.
 
@@ -111,13 +111,13 @@ If no value is specified then the following defaults are used:
 - Hour: `*` (Every hour)
 - Minute: `*` (Every minute)
 
-:::info Day and Day of the week
+:::info[Day and Day of the week]
 
 If either field is set to `*` then use the other field, otherwise the soonest value is used.
 
 :::
 
-#### Examples
+#### Examples {/* #examples */}
 
 ```php title="Run at a fixed time each day, randomised during installation of the task"
 $tasks = [
@@ -147,7 +147,7 @@ $tasks = [
 ];
 ```
 
-### Disabled tasks
+### Disabled tasks {/* #disabled-tasks */}
 
 You can create a task that defaults to disabled by setting the field **disabled** to 1. Unless the administrator manually enables your task, it will not run.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -4,4 +4,4 @@ enableGlobalCache: false

		nodeLinker: node-modules

		yarnPath: .yarn/releases/yarn-4.9.2.cjs
		yarnPath: .yarn/releases/yarn-4.13.0.cjs