update markdownlint and editorconfig configuration

add task targets
add pre-commit config

Author: rpietzsch

.editorconfig

@@ -16,8 +16,9 @@ trim_trailing_whitespace = true
 indent_style = space
 indent_size = 2
 
-# 4 space indentation
-[*.md]
+# Matches multiple files with brace expansion notation
+# Set default charset
+[*.{md}]
 indent_style = space
 indent_size = 4
 

.markdownlint.jsonc

@@ -1,34 +1,45 @@
 {
   // Example markdownlint JSON(C) configuration with all properties set to their default value
-
   // Default state for all rules
   "default": true,
-
   // not enforcing line break a specific lenght
   "MD013": false,
-
   "MD007": {
     "indent": 4
   },
-
   // allow Multiple headings with the same content
   "MD024": false,
-
+  // allow multiple top level headings -> generated files
+  "MD025": false,
   // to be consistent with prettier
   "MD030": {
-    "ul_single": 3,
-    "ul_multi": 3
+    "ul_single": 1,
+    "ul_multi": 1
   },
-
   // allow some html
   "MD033": {
-    "allowed_elements": ["figure", "figcaption", "div"]
+    "allowed_elements": [
+      "figure",
+      "figcaption",
+      "div",
+      "details",
+      "summary",
+      "a",
+      "p",
+      "img",
+      "span",
+      "br"
+    ]
   },
-
+  // not enfore h1 as first content of a file
+  "MD041": false,
   // allow missing img alt text
   "MD045": false,
-
   // disabled due to admonition / tabs using indented blocks
-  "MD046": false
-  //"MD046": { "style": "fenced" }
-}
+  "MD046": false,
+  //"MD046": { "style": "fenced" },
+  // allow non-descriptive link text, like "here"
+  "MD059": false,
+  // relax table formatting rules
+  "MD060": false
+}

.pre-commit-config.yaml

@@ -0,0 +1,11 @@
+
+---
+repos:
+  - repo: local
+    hooks:
+
+      - id: markdownlint
+        name: check:markdownlint
+        entry: task check:markdownlint
+        language: python
+        pass_filenames: false

Taskfile.yml

@@ -180,3 +180,28 @@ tasks:
     cmds:
       - poetry run mike serve -b {{.PUBLIC_BRANCH}}
 
+  format:fix:
+    desc: markdownlit md files and apply possible style fixes
+    cmds:
+      - |
+        {
+          # recurse
+          find ./docs -type f -name '*.md' -print0
+
+          # no recursion (top-level only)
+          find . -maxdepth 1 -type f -name '*.md' -print0
+        } | xargs -0 markdownlint --config .markdownlint.jsonc --fix
+
+  check:markdownlint:
+    desc: run markdownlint on md files for style issues
+    cmds:
+      #- mkdir -p ./dist
+      - |
+        {
+          # recurse
+          find ./docs -type f -name '*.md' -print0
+
+          # no recursion (top-level only)
+          find . -maxdepth 1 -type f -name '*.md' -print0
+        } | xargs -0 markdownlint --config .markdownlint.jsonc
+      # --json --output ./dist/markdownlint-issues.json