Update markdown lint style and option files

Add commented lines explaining the file, and including
rules that should pass already, and commented out rules
that can be added in the future, for reference.

.mdlrc

@@ -1,3 +1,6 @@
+# This is the options file for mdl, configured in .gitlab/ci/docs.gitlab-ci.yml,
+# and related to the style file ./mdlrc.style
+
 # See https://github.com/markdownlint/markdownlint/blob/master/docs/configuration.md
 
 ignore_front_matter true

.mdlrc.style

@@ -1,7 +1,21 @@
-# See https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+# This is the style file for mdl, configured in .gitlab/ci/docs.gitlab-ci.yml,
+# and related to the options file ./mdlrc
 
-rule 'MD001'
+# See https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+# for more detailed information on the rules and styles.
+
+rule "MD001"
+rule "MD003", :style => :atx
+rule "MD011"
+rule "MD023"
+rule "MD032"
+rule "MD034"
+rule "MD037"
+
+# Should not be used currently:
+
+# rule "MD004", :style => :dash # unordered list style - dash
 # False positives, see https://github.com/markdownlint/markdownlint/issues/261
-# rule 'MD004', style: :dash
-rule 'MD032'
-rule 'MD034'
+ 
+# rule "MD039" # Spaces inside link text
+# Crashes when link text has certain punctuation