GH Actions: add new check with additional QA for markdown files

While MarkdownLint is absolutely great for finding formatting issues, Remark offers some additional "rules" which are useful, such as checking that links and link definitions match up, verifying all used links work and some additional formatting checks which markdownlint just doesn't offer.

The rule configuration is contained in the `.remarkrc` file.

Files/directories to be ignored can be listed in the `.remarkignore` file which supports glob syntax, like `.gitignore`.
Note: `.`-prefixed files and directories are excluded by default. To include those in the scan, they have to be passed explicitly on the command-line.

To run locally, follow the same steps as per the GitHub actions workflow.

Note: the workflow contains a double-run of remark-lint to allow viewing the results both in a human readable way in the actions transscripts, as well as getting annotations for found issue in PRs.

Notes about the config:
* An extensive effort has been made to prevent duplication of messages between the Markdownlint and the Remark check. This includes ensuring there are no conflicting rules.
* As the changelog contain a large number of links, at some point the check may run into a rate limit. Excluding contributor links should prevent that for a while.
* The file name check does not allow for the file names GitHub requires for issue templates.
    The provided regex fixes that.
* The "undefined references" check doesn't natively understand arrays in frontmatter, nor the new "callout" syntax supported by GitHub.
    The provided config should prevent false positives for those.

Refs:
* https://github.com/remarkjs/remark/tree/main/packages/remark-cli
* https://github.com/remarkjs/remark-lint
* https://github.com/remarkjs/remark-gfm
* https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-consistent
* https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-recommended
* https://github.com/remarkjs/remark-lint/tree/main/packages/remark-preset-lint-markdown-style-guide

Additional (external) plugins included:
* https://github.com/vhf/remark-lint-heading-whitespace
* https://github.com/wemake-services/remark-lint-list-item-punctuation
* https://github.com/laysent/remark-lint-plugins/tree/HEAD/packages/remark-lint-match-punctuation
* https://github.com/olizilla/remark-lint-no-hr-after-heading
* https://github.com/remarkjs/remark-lint-no-dead-urls
* https://github.com/remarkjs/remark-validate-links

Author: jrfnl

.gitattributes

@@ -11,6 +11,8 @@ scripts/                export-ignore
 .gitattributes          export-ignore
 .gitignore              export-ignore
 .markdownlint-cli2.yaml export-ignore
+.remarkignore           export-ignore
+.remarkrc               export-ignore
 .yamllint.yml           export-ignore
 phpcs.xml.dist          export-ignore
 phpstan.neon.dist       export-ignore

.github/workflows/validate.yml

@@ -4,6 +4,9 @@ on:
   # Run on all pushes and on all pull requests.
   push:
   pull_request:
+  # Also run this workflow every Monday at 6:00 (to make sure the broken link check runs regularly).
+  schedule:
+    - cron: '0 6 * * 1'
   # Allow manually triggering the workflow.
   workflow_dispatch:
 
@@ -94,3 +97,68 @@ jobs:
       # @link https://github.com/marketplace/actions/markdownlint-cli2-action
       - name: Check markdown with CLI2
         uses: DavidAnson/markdownlint-cli2-action@v16
+
+  remark:
+    name: 'QA Markdown'
+    runs-on: ubuntu-latest
+
+    # Don't run the cronjob in this workflow on forks.
+    if: github.event_name != 'schedule' || (github.event_name == 'schedule' && github.repository_owner == 'PHPCSStandards')
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up node and enable caching of dependencies
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      # To make the command available on CLI, it needs to be installed globally.
+      - name: Install Remark CLI globally
+        run: npm install --global remark-cli --foreground-scripts true --fund false
+
+      # To allow for creating a custom config which references rules which are included
+      # in the presets, without having to install all rules individually, a local install
+      # works best (and installing the presets in the first place, of course).
+      #
+      # Note: the first group of packages are all part of the mono "Remark lint" repo.
+      # The second group of packages (heading-whitespace and down) are additional
+      # "external" rules/plugins.
+      - name: Install Remark rules locally
+        run: >
+          npm install --foreground-scripts true --fund false
+          remark-lint
+          remark-gfm
+          remark-preset-lint-consistent
+          remark-preset-lint-recommended
+          remark-preset-lint-markdown-style-guide
+          remark-lint-checkbox-content-indent
+          remark-lint-linebreak-style
+          remark-lint-no-dead-urls
+          remark-lint-no-duplicate-defined-urls
+          remark-lint-no-empty-url
+          remark-lint-no-heading-like-paragraph
+          remark-lint-no-reference-like-url
+          remark-lint-no-unneeded-full-reference-image
+          remark-lint-no-unneeded-full-reference-link
+          remark-lint-strikethrough-marker
+          remark-lint-heading-whitespace
+          remark-lint-list-item-punctuation
+          remark-lint-match-punctuation
+          remark-lint-no-hr-after-heading
+          remark-lint-are-links-valid-duplicate
+          remark-validate-links
+
+      - name: Run Remark-lint
+        run: remark . --frail
+
+      # @link https://github.com/reviewdog/action-remark-lint
+      - name: Show Remark-lint annotations in PR
+        if: ${{ failure() && github.event_name == 'pull_request' }}
+        uses: reviewdog/action-remark-lint@v5
+        with:
+          fail_on_error: true
+          install_deps: false
+          level: info
+          reporter: github-pr-check

.remarkignore

@@ -0,0 +1,5 @@
+# Ignore rules for Remark.
+# Docs: https://github.com/unifiedjs/unified-engine/blob/HEAD/doc/ignore.md
+
+/node_modules/
+/vendor/

.remarkrc

@@ -0,0 +1,56 @@
+{
+  "plugins": [
+    "remark-gfm",
+    ["remark-lint-checkbox-character-style", "consistent"],
+    ["remark-lint-checkbox-content-indent", "consistent"],
+    "remark-lint-definition-spacing",
+    "remark-lint-file-extension",
+    ["remark-lint-linebreak-style", "unix"],
+    ["remark-lint-link-title-style", "\""],
+    ["remark-lint-ordered-list-marker-style", "."],
+    [
+        "remark-lint-no-dead-urls",
+        {
+            "skipUrlPatterns": [
+                "^https?://github\\.com/PHPCSStandards/PHP_CodeSniffer/compare/[0-9\\.]+?\\.{3}[0-9\\.]+",
+                "^https?://github\\.com/[A-Za-z0-9-]+"
+            ]
+        }
+    ],
+    "remark-lint-no-duplicate-defined-urls",
+    "remark-lint-no-duplicate-definitions",
+    "remark-lint-no-empty-url",
+    "remark-lint-no-file-name-consecutive-dashes",
+    ["remark-lint-no-file-name-irregular-characters", "\\.a-zA-Z0-9-_"],
+    "remark-lint-no-file-name-outer-dashes",
+    "remark-lint-no-heading-like-paragraph",
+    "remark-lint-no-literal-urls",
+    "remark-lint-no-reference-like-url",
+    "remark-lint-no-shortcut-reference-image",
+    "remark-lint-no-table-indentation",
+    [
+        "remark-lint-no-undefined-references",
+        {
+            "allow": [
+                "!NOTE",
+                "!TIP",
+                "!IMPORTANT",
+                "!WARNING",
+                "!CAUTION",
+                "'Status: triage', 'Type: bug'",
+                "'Status: triage', 'Type: enhancement'"
+            ]
+        }
+    ],
+    "remark-lint-no-unneeded-full-reference-image",
+    "remark-lint-no-unneeded-full-reference-link",
+    "remark-lint-no-unused-definitions",
+    ["remark-lint-strikethrough-marker", "~~"],
+    "remark-lint-heading-whitespace",
+    "remark-lint-list-item-punctuation",
+    "remark-lint-match-punctuation",
+    "remark-lint-no-hr-after-heading",
+    "remark-lint-are-links-valid-duplicate",
+    "remark-validate-links"
+  ]
+}