Centralize config for markdownlint

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.

9 files changed, 36 insertions, 11 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 f567eac3ee0..33f9c4650ef 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 668cfff4fb4..c8b8f0e4f90 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
diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md
index 816bd35018a..2d7fb323d79 100644
--- a/doc/ci/docker/using_docker_images.md
+++ b/doc/ci/docker/using_docker_images.md
@@ -530,11 +530,11 @@ There are two ways to determine the value of `DOCKER_AUTH_CONFIG`:
     ```
 
 - **Second way -** In some setups, it's possible that Docker client
-will use the available system keystore to store the result of `docker
-login`. In that case, it's impossible to read `~/.docker/config.json`,
-so you will need to prepare the required base64-encoded version of
-`${username}:${password}` manually. Open a terminal and execute the
-following command:
+  will use the available system keystore to store the result of `docker
+  login`. In that case, it's impossible to read `~/.docker/config.json`,
+  so you will need to prepare the required base64-encoded version of
+  `${username}:${password}` manually. Open a terminal and execute the
+  following command:
 
     ```bash
     echo -n "my_username:my_password" | base64
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 7127efb7405..d9cea0614c3 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -518,7 +518,7 @@ you have your MR reviewed and approved by a technical writer.
 ```html
 leave a blank line here
 <div class="video-fallback">
-  See the video: [Video title](https://www.youtube.com/watch?v=MqL6BMOySIQ).
+  See the video: <a href="https://www.youtube.com/watch?v=MqL6BMOySIQ">Video title</a>.
 </div>
 <figure class="video-container">
   <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe>
@@ -529,7 +529,7 @@ leave a blank line here
 This is how it renders on docs.gitlab.com:
 
 <div class="video-fallback">
-  See the video: [What is GitLab](https://www.youtube.com/watch?v=enMumwvLAug).
+  See the video: <a href="https://www.youtube.com/watch?v=enMumwvLAug">What is GitLab</a>.
 </div>
 <figure class="video-container">
   <iframe src="https://www.youtube.com/embed/MqL6BMOySIQ" frameborder="0" allowfullscreen="true"> </iframe>
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index 5e11e7c0203..72594733cd3 100644
--- a/doc/user/project/deploy_tokens/index.md
+++ b/doc/user/project/deploy_tokens/index.md
@@ -41,7 +41,7 @@ the following table.
 
 ## Deploy token custom username
 
-> [Introduced][https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29639] in GitLab 12.1.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29639) in GitLab 12.1.
 
 The default username format is `gitlab+deploy-token-#{n}`. Some tools or platforms may not support this format,
 in such case you can specify custom username to be used when creating the deploy token.