diff --git a/.markdownlint.jsonc b/.markdownlint.jsonc
index e58deb58a..199995de6 100644
--- a/.markdownlint.jsonc
+++ b/.markdownlint.jsonc
@@ -4,16 +4,29 @@
   // Default state for all rules
   "default": true,
 
-  // Changed to allow indented code
+  // MkDocs assumes 4 spaces for indentation.
+  // Markdown assumes 4 spaces for indentation.
+  // That markdownlint has a different default is the error of markdownlint
+  "MD007": { "indent": 4 },
+
+  // Standard markdown does not allow for two correct consecutive blank lines 
+  // i an admonitions (a.o. the 'question' admonition):
+  //
+  // ???- question "A question"
+  //
+  //     ```
+  //     echo "indented code here :-)
+  //     ````
+  //     [blank line 1 here]
+  // [blank line 2 here]
+  //
+  // Hence we allow 2 consecutive blank lines
   //
-  // MD012/no-multiple-blanks : Multiple consecutive blank lines : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md012.md
   "MD012": {
     // Consecutive blank lines, CHANGED FROM 1
-    "maximum": 100
+    "maximum": 2
   },
 
-  // Changed to allow indented code
-  //
   "MD013": {
     // Number of characters, CHANGED FROM 80
     "line_length": 800,
@@ -33,16 +46,22 @@
     "stern": false
   },
 
+  // It is common that content creators start their consoles with a dollar,
+  // likely because they think it is clearer
   //MD014/commands-show-output: Show dollar before command : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md014.md
   "MD014": false,
 
-  // Changed to allow indented code
+  // Standard markdown does not allow for valid indent code like this:
+  //
+  // ???- question "A question"
+  //
+  //     ```
+  //     echo "indented code here :-)
+  //     ````
+  //     
+  // Hence we allow valid indented code.
   //
   // MD046/code-block-style : Code block style : https://github.com/DavidAnson/markdownlint/blob/v0.34.0/doc/md046.md
   "MD046": false
-  //"MD046": {
-  //  // Block style
-  //  "style": "consistent"
-  //},
 
 }