Centralize config for markdownlintcentralize-markdownlint-config

The configuration is currently only specified in CI, by moving it into
`.mdlrc` we get immediate feedback locally in supported editors.

To ensure `mdl` is available it's also added to the `Gemfile`, though
CI will still use the version installed in the `gitlab-docs-lint` image.

6 files changed, 28 insertions, 3 deletions

diff --git a/.gitlab/ci/docs.gitlab-ci.yml b/.gitlab/ci/docs.gitlab-ci.yml
index 57ee91e4385..5bc109f2b7f 100644
--- a/.gitlab/ci/docs.gitlab-ci.yml
+++ b/.gitlab/ci/docs.gitlab-ci.yml
@@ -66,9 +66,7 @@ docs lint:
     - mv doc/ /tmp/gitlab-docs/content/$DOCS_GITLAB_REPO_SUFFIX
     - cd /tmp/gitlab-docs
     # Lint Markdown
-    # https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
-    - bundle exec mdl content/$DOCS_GITLAB_REPO_SUFFIX/**/*.md --ignore-front-matter --rules \
-        MD001,MD032,MD034
+    - bundle exec mdl content/$DOCS_GITLAB_REPO_SUFFIX -c $CI_PROJECT_DIR/.mdlrc
     # Build HTML from Markdown
     - bundle exec nanoc
     # Check the internal links
diff --git a/.mdlrc b/.mdlrc
new file mode 100644
index 00000000000..b2127dadc22
--- /dev/null
+++ b/.mdlrc
@@ -0,0 +1,4 @@
+# See https://github.com/markdownlint/markdownlint/blob/master/docs/configuration.md
+
+ignore_front_matter true
+style File.expand_path('.mdlrc.style', __dir__)
diff --git a/.mdlrc.style b/.mdlrc.style
new file mode 100644
index 00000000000..30abf03f462
--- /dev/null
+++ b/.mdlrc.style
@@ -0,0 +1,7 @@
+# See https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
+
+rule 'MD001'
+# False positives, see https://github.com/markdownlint/markdownlint/issues/261
+# rule 'MD004', style: :dash
+rule 'MD032'
+rule 'MD034'
diff --git a/Gemfile b/Gemfile
index d95e57cf168..34d8b87909d 100644
--- a/Gemfile
+++ b/Gemfile
@@ -368,6 +368,7 @@ group :development, :test do
   gem 'haml_lint', '~> 0.31.0', require: false
   gem 'simplecov', '~> 0.16.1', require: false
   gem 'bundler-audit', '~> 0.5.0', require: false
+  gem 'mdl', '~> 0.5.0', require: false
 
   gem 'benchmark-ips', '~> 2.3.0', require: false
 
diff --git a/Gemfile.lock b/Gemfile.lock
index 363baa5f9d5..864d0422a96 100644
--- a/Gemfile.lock
+++ b/Gemfile.lock
@@ -459,6 +459,7 @@ GEM
     kgio (2.11.2)
     knapsack (1.17.0)
       rake
+    kramdown (1.17.0)
     kubeclient (4.2.2)
       http (~> 3.0)
       recursive-open-struct (~> 1.0, >= 1.0.4)
@@ -492,6 +493,10 @@ GEM
     mail (2.7.1)
       mini_mime (>= 0.1.1)
     mail_room (0.9.1)
+    mdl (0.5.0)
+      kramdown (~> 1.12, >= 1.12.0)
+      mixlib-cli (~> 1.7, >= 1.7.0)
+      mixlib-config (~> 2.2, >= 2.2.1)
     memoist (0.16.0)
     memoizable (0.4.2)
       thread_safe (~> 0.3, >= 0.3.1)
@@ -505,6 +510,9 @@ GEM
     mini_mime (1.0.1)
     mini_portile2 (2.4.0)
     minitest (5.11.3)
+    mixlib-cli (1.7.0)
+    mixlib-config (2.2.18)
+      tomlrb
     msgpack (1.2.10)
     multi_json (1.13.1)
     multi_xml (0.6.0)
@@ -943,6 +951,7 @@ GEM
       parslet (~> 1.8.0)
     toml-rb (1.0.0)
       citrus (~> 3.0, > 3.0)
+    tomlrb (1.2.8)
     truncato (0.7.11)
       htmlentities (~> 4.3.1)
       nokogiri (>= 1.7.0, <= 2.0)
@@ -1134,6 +1143,7 @@ DEPENDENCIES
   lograge (~> 0.5)
   loofah (~> 2.2)
   mail_room (~> 0.9.1)
+  mdl (~> 0.5.0)
   memory_profiler (~> 0.9)
   method_source (~> 0.8)
   mimemagic (~> 0.3.2)
diff --git a/changelogs/unreleased/centralize-markdownlint-config.yml b/changelogs/unreleased/centralize-markdownlint-config.yml
new file mode 100644
index 00000000000..9ca36078cf1
--- /dev/null
+++ b/changelogs/unreleased/centralize-markdownlint-config.yml
@@ -0,0 +1,5 @@
+---
+title: Centralize markdownlint configuration
+merge_request: 30263
+author:
+type: other