Update docs linting to markdownlint-cli2 and enforce no-space-after-fence rule

.github/.markdownlint-cli2.jsonc

@@ -0,0 +1,83 @@
+{
+  "config": {
+    "default": true,
+    "heading-increment": true,
+    "no-hard-tabs": true,
+    "no-multiple-blanks": true,
+    "line-length": false,
+    "commands-show-output": true,
+    "blanks-around-headings": true,
+    "heading-start-left": true,
+    "no-duplicate-heading": false,
+    "single-h1": false,
+    "no-trailing-punctuation": false,
+    "no-blanks-blockquote": false,
+    "list-marker-space": true,
+    "blanks-around-fences": true,
+    "blanks-around-lists": true,
+    "no-inline-html": {
+      "allowed_elements": [
+        "Badge",
+        "div",
+        "span",
+        "br",
+        "style",
+        "details",
+        "summary",
+        "table",
+        "thead",
+        "tbody",
+        "tr",
+        "th",
+        "td",
+        "img",
+        "a",
+        "svg",
+        "path",
+        "figure",
+        "p",
+        "colgroup",
+        "col",
+        "strong",
+        "sup",
+        "section",
+        "hr",
+        "ol",
+        "ul",
+        "li",
+        "em",
+        "code"
+      ]
+    },
+    "no-bare-urls": true,
+    "fenced-code-language": true,
+    "first-line-heading": false,
+    "code-block-style": false,
+    "code-fence-style": {
+      "style": "backtick"
+    },
+    "emphasis-style": {
+      "style": "asterisk"
+    },
+    "strong-style": {
+      "style": "asterisk"
+    },
+    "spaces-after-emphasis-marker": true,
+    "spaces-after-code-fence-info": true,
+    "spaces-inside-emphasis-markers": true,
+    "spaces-inside-code-span-elements": true,
+    "single-trailing-newline": true,
+    "link-fragments": false,
+    "table-pipe-style": "leading_and_trailing",
+    "table-column-count": false,
+    "table-column-style": false,
+    "descriptive-link-text": false,
+    "no-emphasis-as-heading": false
+  },
+  "customRules": [
+    "./markdownlint-rules/no-space-after-fence.js"
+  ],
+  "ignores": [
+    "node_modules/**"
+  ]
+}

.github/markdownlint-rules/no-space-after-fence.js

@@ -0,0 +1,35 @@
+"use strict";
+
+module.exports = {
+  names: ["no-space-after-fence"],
+  description: "Disallow spaces between a fence and the info string.",
+  tags: ["code", "fences", "whitespace"],
+  function: function noSpaceAfterFence(params, onError) {
+    const lines = params.lines || [];
+
+    (params.tokens || []).forEach((token) => {
+      if (token.type !== "fence") {
+        return;
+      }
+
+      if (!token.markup || token.markup[0] !== "`") {
+        return;
+      }
+
+      if (!token.map || token.map.length === 0) {
+        return;
+      }
+
+      const lineNumber = token.map[0] + 1;
+      const line = lines[lineNumber - 1] || "";
+
+      if (/^\s*`{3,}[ \t]+\S/.test(line)) {
+        onError({
+          lineNumber,
+          detail: "Remove the space between the fence and the info string.",
+          context: line.trim()
+        });
+      }
+    });
+  }
+};

.github/workflows/docs-validation.yml

@@ -57,11 +57,10 @@ jobs:
         uses: actions/checkout@v6
 
       - name: Lint markdown files
-        uses: articulate/actions-markdownlint@v1
+        uses: DavidAnson/markdownlint-cli2-action@v22
         with:
-          config: .github/markdownlint.json
-          files: 'docs/**/*.md'
-          ignore: 'node_modules'
+          config: './.github/.markdownlint-cli2.jsonc'
+          globs: 'docs/**/*.md'
 
   spell-check:
     name: Spell Check

docs/en/appendices/5-0-migration-guide.md

@@ -225,15 +225,15 @@ high memory usage due to the entire result set being buffered in memory.
 
 You can work around this issue by disabling results buffering for the query:
 
-``` php
+```php
 $results = $articles->find()
     ->disableBufferedResults()
     ->all();
 ```
 
 Depending on your use case, you may also consider using disabling hydration:
 
-``` php
+```php
 $results = $articles->find()
     ->disableHydration()
     ->all();
@@ -350,7 +350,7 @@ properties more strictly. The new behavior is called 'required fields'. When
 enabled, accessing properties that are not defined in the entity will raise
 exceptions. This impacts the following usage:
 
-``` php
+```php
 $entity->get();
 $entity->has();
 $entity->getOriginal();
@@ -368,7 +368,7 @@ this the default behavior in the future.
 Table finders can now have typed arguments as required instead of an options array.
 For e.g. a finder for fetching posts by category or user:
 
-``` php
+```php
 public function findByCategoryOrUser(SelectQuery $query, array $options): SelectQuery
 {
     if (isset($options['categoryId'])) {
@@ -384,7 +384,7 @@ public function findByCategoryOrUser(SelectQuery $query, array $options): Select
 
 can now be written as:
 
-``` php
+```php
 public function findByCategoryOrUser(SelectQuery $query, ?int $categoryId = null, ?int $userId = null): SelectQuery
 {
     if ($categoryId) {
@@ -404,7 +404,7 @@ You can even include the special named arguments for setting query clauses.
 
 A similar change has been applied to the `RepositoryInterface::get()` method:
 
-``` php
+```php
 public function view(int $id)
 {
     $author = $this->Authors->get($id, [
@@ -416,7 +416,7 @@ public function view(int $id)
 
 can now be written as:
 
-``` php
+```php
 public function view(int $id)
 {
     $author = $this->Authors->get($id, contain: ['Books'], finder: 'latest');

docs/en/appendices/5-0-upgrade-guide.md

@@ -11,7 +11,7 @@ First, check that your application is running on latest CakePHP 4.x version.
 
 Once your application is running on latest CakePHP 4.x, enable deprecation warnings in **config/app.php**:
 
-``` php
+```php
 'Error' => [
     'errorLevel' => E_ALL,
 ],
@@ -43,7 +43,7 @@ Because CakePHP 5 leverages union types and `mixed`, there are many
 backwards incompatible changes concerning method signatures and file renames.
 To help expedite fixing these tedious changes there is an upgrade CLI tool:
 
-``` bash
+```bash
 # Install the upgrade tool
 git clone https://github.com/cakephp/upgrade
 cd upgrade
@@ -54,7 +54,7 @@ composer install --no-dev
 With the upgrade tool installed you can now run it on your application or
 plugin:
 
-``` bash
+```bash
 bin/cake upgrade rector --rules cakephp50 <path/to/app/src>
 bin/cake upgrade rector --rules chronos3 <path/to/app/src>
 ```

docs/en/appendices/5-1-migration-guide.md

@@ -15,7 +15,7 @@ The [upgrade tool](../appendices/migration-guides) provides rector rules for
 automating some of the migration work. Run rector before updating your
 `composer.json` dependencies:
 
-``` bash
+```bash
 bin/cake upgrade rector --rules cakephp51 <path/to/app/src>
 ```
 

docs/en/appendices/5-2-migration-guide.md

@@ -15,7 +15,7 @@ The [upgrade tool](../appendices/migration-guides) provides rector rules for
 automating some of the migration work. Run rector before updating your
 `composer.json` dependencies:
 
-``` bash
+```bash
 bin/cake upgrade rector --rules cakephp52 <path/to/app/src>
 ```
 

docs/en/appendices/5-3-migration-guide.md

@@ -15,7 +15,7 @@ The [upgrade tool](../appendices/migration-guides) provides rector rules for
 automating some of the migration work. Run rector before updating your
 `composer.json` dependencies:
 
-``` bash
+```bash
 bin/cake upgrade rector --rules cakephp53 <path/to/app/src>
 ```