Skip to main content

Linting and other checks

In order to keep the quality of the documentation as high as possible, we perform a range of linting and spelling checks. These include:

Helper scripts are included to make this easier and, where possible, to automatically fix issues.

We also attempt to perform these as pre-commit checks which prevent your from commit invalid changes.

Spelling​

All documentation is checked using CSpell against the en-GB dictionary.

A number of additional dictionaries are also included:

Where you encounter such a spelling and need it to be ignored, you should either:

  • ignore the spelling within the current file; or
  • add it as a valid spelling across the entire repository.

To ignore a spelling error within a single file, you can use an HTML comment:

Ignoring a single word
<!-- cspell:ignore yourword -->

You can ignore multiple words in the same comment by separating them with a comma, for example:

Ignoring multiple words
<!-- cspell:ignore yourword,goeshere -->

If the word you are using is a word which will be frequently used across the project, then you should add it to the relevant spelling list.

Spelling lists​

Contributors​

A list of Moodle Contributors is compiled from the Moodle git repository. This allows you use the name of any contributor in the documentation without any errors being generated.

danger

This list is automatically updated once per week, after the weekly release.

This list should not be updated manually.

Component and plugin types​

A list of all Moodle Component types and plugin types is compiled from the Moodle git repository.

danger

This list is automatically updated once per week, after the weekly release.

This list should not be updated manually.

note

This list does not currently include the complete list of plugins. If you need to mention a plugin whose name is not a valid spelling, you will currently need to manually add this to the plugin names list.

This will be included at a later date. See #282 for more information.

Plugin names​

Plugin names are currently not generated automatically (but will be in the future). As a result, if you need to specify a plugin which does not have a valid spelling then it should be added to the manually-controlled list of spellings.

note

Moodle core plugins will be automatically generated in future. See #282.

This file will be kept for third-party plugins.

Project words​

In many situations we use words which are not 'real' words. This could be because they are concatenations of words, abbreviations, Moodle-isms, people's names, the names of organisations, or a host of other reasons.

For any words which does not fit into the above categories, you can place it into the project-words.txt file.

Markdown Checks​

We make use of markdownlint-cli2 to run a number of style and validation checks on all files with both the .md and .mdx file extensions.

These checks cover both standard rules, and several custom rules with examples including:

Whenever you make changes to the documentation, we strongly recommend running yarn fix to check that all markdown files meet our standards, fix any issues (including updating links to migrated pages), and are free from spelling mistakes.

yarn fix

This command will:

  • Run our standard linting rules against all markdown and mdx files
  • Automatically fix any warnings which can be automatically fixed
  • Report any warnings which could not be fixed

This command should be extremely fast to run, but you may also wish to check just one file. You can do using the yarn mdlint [path/to/file] command, for example:

Lint just the general/documentation/linting.md file
yarn lint general/documentation/linting.md

Ignoring lint issues​

Although it should rarely happen, you will occasinoally need to ignore markdownlint failures instead of fixing them.

See the markdownlint documentation for examples of the different syntax available to do this.

When we build the documentation using Docusaurus, the build system checks for any broken internal links.

yarn build
info

This test is slightly slower to run, and we recommend that you run it as the final check before you push.