customize markdownlint to avoid too many warnings

We had to create a style because we can't just use a `.mdlrc` if we
want to customize some rule settings (e.g. for rule MD026).

.mdlrc

+# this is a markdownlint configuration file, see this documentation
+# for more information:
+# https://github.com/markdownlint/markdownlint/blob/master/docs/configuration.md
+
+# this includes our default style in the styles/ subdirectory, next to
+# this configuration file
+style "#{File.dirname(__FILE__)}/styles/default.rb"
+
+# this will show compile-time warnings from the Kramdown engine, which
+# will identify errors like [link][target] without a [target]:.
+show_kramdown_warnings true

styles/default.rb

+all
+
+# no rationale provided by markdownlint, too many matches
+exclude_tag :line_length
+# trailing spaces, no rationale provided by markdownlint, too many matches
+exclude_rule "MD009"
+# "starting bulleted lists at the beginning of the line", too many matches
+exclude_rule "MD006"
+# "Header style", default is "consistent", would be better to set to
+# ATX (because it makes "outlines" and grepping more readable), but
+# too many matches
+exclude_rule "MD003"
+# Code block style, no rationale provided, seems legit to mix ``` and prefixes
+exclude_rule "MD046"
+# Ordered list item prefix, allow 1. 1. 1. and 1.2.3....
+exclude_rule "MD029"
+# Bare URL used, seems legit, but too many matches.
+exclude_rule "MD034"
+# "Fenced code blocks should have a language specified", we have too
+# many shell scripts and random samples
+exclude_rule "MD040"
+# "First line in file should be a top level header"
+#
+# it's fine to start a document without a heading. it's called a
+# lead. the document title should be in the front matter, not in a
+# heading
+exclude_rule "MD041"
+
+# allow exclamation marks and question marks in headings
+rule 'MD026', :punctuation => ".,;:"