add markdownlint (#2244)

.github/workflows/markdownlint-problem-matcher.json

@@ -0,0 +1,17 @@
+{
+    "problemMatcher": [
+        {
+            "owner": "markdownlint",
+            "pattern": [
+                {
+                    "regexp": "^([^:]*):(\\d+):?(\\d+)?\\s([\\w-\\/]*)\\s(.*)$",
+                    "file": 1,
+                    "line": 2,
+                    "column": 3,
+                    "code": 4,
+                    "message": 5
+                }
+            ]
+        }
+    ]
+}

.github/workflows/markdownlint.yml

@@ -0,0 +1,26 @@
+name: Markdownlint
+
+permissions:
+  contents: read
+
+# run even on changes without markdown changes, so that we can
+# make it in GitHub a required check for PR's
+on:
+  pull_request:
+
+jobs:
+  lint:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+    - name: Use Node.js
+      uses: actions/setup-node@v3
+      with:
+        node-version: 16.x
+    - name: Run Markdownlint
+      run: |
+        echo "::add-matcher::.github/workflows/markdownlint-problem-matcher.json"
+        npm i -g markdownlint-cli
+        markdownlint "**.md"

.markdownlint.json

@@ -0,0 +1,22 @@
+{
+    "default": true,
+    "ul-indent":                       false,
+    "no-trailing-spaces":              false,
+    "line-length":                     false,
+    "blanks-around-headings":          false,
+    "no-duplicate-heading":            { "siblings_only": true },
+    "no-trailing-punctuation":         false,
+    "ol-prefix":                       { "one_or_ordered": true },
+    "blanks-around-fences":            false,
+    "blanks-around-lists":             false,
+    "no-inline-html":                  { "allowed_elements": [ "summary", "details" ]},
+    "no-bare-urls":                    false,
+    "single-trailing-newline":         false,
+    "emphasis-style":                  false,
+    "first-line-heading":              false,
+    "no-space-in-code":                false,
+
+    // rule settings and options are documented in https://github.com/DavidAnson/markdownlint
+    // feel free to disable more low value rules in here; get rule name from the error message.
+    // the purpose of the linter is to catch significant issues like broken links.
+}