GH Actions: add markdown lint + QA jobs

.gitattributes

@@ -5,15 +5,18 @@
 # https://www.reddit.com/r/PHP/comments/2jzp6k/i_dont_need_your_tests_in_my_production/
 # https://blog.madewithlove.be/post/gitattributes/
 #
-.github/          export-ignore
-scripts/          export-ignore
-.cspell.json      export-ignore
-.gitattributes    export-ignore
-.gitignore        export-ignore
-.yamllint.yml     export-ignore
-phpcs.xml.dist    export-ignore
-phpstan.neon.dist export-ignore
-phpunit.xml.dist  export-ignore
+.github/                export-ignore
+scripts/                export-ignore
+.cspell.json            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
+phpunit.xml.dist        export-ignore
 
 #
 # Declare files that should always have CRLF line endings on checkout.

.github/workflows/validate.yml

@@ -2,11 +2,11 @@ name: Validate
 
 on:
   # Run on all pushes and on all pull requests.
-  # Prevent the build from running when there are only irrelevant changes.
   push:
-    paths-ignore:
-      - '**.md'
   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:
 
@@ -78,3 +78,87 @@ jobs:
       - name: Pipe Yamllint results on to GH for inline display
         if: ${{ failure() }}
         run: yamllint . --format github --strict
+
+  markdownlint:
+    name: 'Lint 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
+
+      # @link https://github.com/marketplace/actions/problem-matcher-for-markdownlint-cli
+      - name: Enable showing issue in PRs
+        uses: xt0rted/markdownlint-problem-matcher@v3
+
+      # @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

.gitignore

@@ -7,3 +7,4 @@
 /vendor/
 composer.lock
 phpstan.neon
+/node_modules/

.markdownlint-cli2.yaml

@@ -0,0 +1,109 @@
+#
+# Configuration file for MarkdownLint-CLI2.
+#
+# Example file with all options:
+# https://github.com/DavidAnson/markdownlint-cli2/blob/main/test/markdownlint-cli2-yaml-example/.markdownlint-cli2.yaml
+# Example file with all rules:
+# https://github.com/DavidAnson/markdownlint/blob/main/schema/.markdownlint.yaml
+#
+
+# Define glob expressions to use (only valid at root).
+globs:
+  - "**/*.md"
+  - ".github/**/*.md"
+
+# Show found files on stdout (only valid at root)
+showFound: true
+
+# Define glob expressions to ignore.
+ignores:
+  - "node_modules/"
+  - "vendor/"
+
+# Disable inline config comments.
+noInlineConfig: true
+
+# Disable progress on stdout (only valid at root).
+noProgress: false
+
+# Adjust the configuration for some built-in rules.
+# For full information on the options and defaults, see:
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md
+config:
+  ######################
+  # Disable a few rules.
+  ######################
+  # MD031/blanks-around-fences - Fenced code blocks should be surrounded by blank lines.
+  MD031: false
+  # MD032/blanks-around-lists - Lists should be surrounded by blank lines.
+  MD032: false
+
+  ##############################
+  # Customize a few other rules.
+  ##############################
+  # MD003/heading-style/header-style - Heading style.
+  MD003:
+    # Heading style - Always use hashes.
+    style: "atx"
+
+  # MD007/ul-indent - Unordered list indentation.
+  MD007:
+    indent: 4
+    # Whether to indent the first level of the list.
+    start_indented: false
+
+  # MD012/no-multiple-blanks - Multiple consecutive blank lines.
+  MD012:
+    maximum: 2
+
+  # MD013/line-length - Line length.
+  MD013:
+    # Number of characters. No need for being too fussy.
+    line_length: 1000
+    # Number of characters for headings.
+    heading_line_length: 100
+    # Number of characters for code blocks.
+    code_block_line_length: 100
+    # Stern length checking (applies to tables, code blocks etc which have their own max line length).
+    stern: true
+
+  # MD022/blanks-around-headings : Headings should be surrounded by blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md022.md
+  MD022:
+    # Blank lines above heading
+    lines_above: [2, 1, 1, 1, 1]
+    # Blank lines below heading
+    lines_below: [1, 1, -1, -1, -1]
+
+  # MD024/no-duplicate-heading/no-duplicate-header - Multiple headings with the same content.
+  MD024:
+    # Only check sibling headings.
+    siblings_only: true
+
+  # MD033/no-inline-html - Inline HTML.
+  MD033:
+    # Allowed elements.
+    allowed_elements:
+      - div
+
+  # MD044/proper-names - Proper names should have the correct capitalization.
+  MD044:
+    # List of proper names.
+    names: ["PHP", "PHP_CodeSniffer", "CodeSniffer", "PHPUnit", "Xdebug"]
+    # Include code blocks.
+    code_blocks: false
+
+  # MD046/code-block-style - Code block style
+  MD046:
+    style: "fenced"
+
+  # MD048/code-fence-style - Code fence style
+  MD048:
+    style: "backtick"
+
+  # MD049/emphasis-style - Emphasis style should be consistent
+  MD049:
+    style: "underscore"
+
+  # MD050/strong-style - Strong style should be consistent
+  MD050:
+    style: "asterisk"

.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"
+  ]
+}