build: add markdownlint configuration

.markdownlint.yml

@@ -0,0 +1,43 @@
+default: true
+
+# Use specific styles, to be consistent accross all documents.
+# Default is to accept any as long as it is consistent within the same document.
+heading-style: # MD003
+  style: atx
+ul-style: # MD004
+  style: dash
+hr-style: # MD035
+  style: ---
+code-block-style: # MD046
+  style: fenced
+code-fence-style: # MD048
+  style: backtick
+emphasis-style: # MD049
+  style: asterisk
+strong-style: # MD050
+  style: asterisk
+
+# Allow multiple headers with same text as long as they are not siblings.
+no-duplicate-heading: # MD024
+  siblings_only: true
+
+# Allow long lines in code blocks and tables.
+line-length: # MD013
+  code_blocks: false
+  tables: false
+
+# The Markdown files used to generated docs with Hugo contain a top level
+# header, even though the YAML front matter has a title property (which is
+# used for the HTML document title only). Suppress Markdownlint warning:
+# Multiple top-level headings in the same document.
+single-title: # MD025
+  level: 1
+  front_matter_title:
+
+# The HTML docs generated by Hugo from Markdown files may have slightly
+# different header anchors than GitHub rendered Markdown, e.g. Hugo trims
+# leading dashes so "--config string" becomes "#config-string" while it is
+# "#--config-string" in GitHub preview. When writing links to headers in the
+# Markdown files we must use whatever works in the final HTML generated docs.
+# Suppress Markdownlint warning: Link fragments should be valid.
+link-fragments: false # MD051