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.

.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

.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__)

.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'

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
 

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)

changelogs/unreleased/centralize-markdownlint-config.yml

@@ -0,0 +1,5 @@
+---
+title: Centralize markdownlint configuration
+merge_request: 30263
+author:
+type: other

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

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>

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.