github action mdformat

Ensure all markdown files are formatted in compliance with CommonMark
using the mdformat tool.

Author: ClaCodes

.cspell/project-words.txt

@@ -3,3 +3,4 @@ gitspell
 shellcheck
 shfmt
 yamlfix
+mdformat

.github/actions/mdformat/action.yml

@@ -0,0 +1,12 @@
+---
+name: mdformat
+description: Checks CommonMark formatting of md files with mdformat
+runs:
+  using: composite
+  steps:
+    - run: pip install mdformat
+      shell: bash
+    - run: echo "::add-matcher::.github/matchers/fmt.json"
+      shell: bash
+    - run: ./scripts/mdformat.sh
+      shell: bash

.github/workflows/main.yml

@@ -60,3 +60,8 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - uses: ./.github/actions/yamlfix
+  mdformat:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/mdformat

scripts/mdformat.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+mdformat --version
+EXIT_CODE=0
+FILES=$(find . -name "*.md")
+for FILE in $FILES; do
+    if [ "$1" == "--diff" ]; then
+        cp "$FILE" "$FILE.temp"
+        mdformat "$FILE.temp"
+        if ! diff --unified "$FILE" "$FILE.temp"; then
+            EXIT_CODE=1
+        fi
+        rm "$FILE.temp"
+    elif [ "$1" == "--apply" ]; then
+        mdformat "$FILE"
+    else
+        if ! mdformat --check "$FILE" 2>/dev/null; then
+            printf "%s;; \`mdformat\` would format this file. It should comply with CommonMark. Use \`./scripts/mdformat.sh --diff\` to see the changes it would make and \`./scripts/mdformat.sh --apply\` to apply them.\n" "$FILE"
+            EXIT_CODE=1
+        fi
+    fi
+done
+
+exit "$EXIT_CODE"