Merge branch 'mdl-to-markdownlint' into 'master'

Change mdl to markdownlint for docs linting

Closes #65806

See merge request gitlab-org/gitlab-ce!31994

10 files changed, 55 insertions, 64 deletions

diff --git a/.gitlab/ci/docs.gitlab-ci.yml b/.gitlab/ci/docs.gitlab-ci.yml
index 39ae62a43c9..d724ab07663 100644
--- a/.gitlab/ci/docs.gitlab-ci.yml
+++ b/.gitlab/ci/docs.gitlab-ci.yml
@@ -65,7 +65,7 @@ docs lint:
     - mv doc/ /tmp/gitlab-docs/content/$DOCS_GITLAB_REPO_SUFFIX
     - cd /tmp/gitlab-docs
     # Lint Markdown
-    - bundle exec mdl content/$DOCS_GITLAB_REPO_SUFFIX -c $CI_PROJECT_DIR/.mdlrc
+    - markdownlint --config $CI_PROJECT_DIR/.markdownlint.json content/$DOCS_GITLAB_REPO_SUFFIX/**/*.md
     # Build HTML from Markdown
     - bundle exec nanoc
     # Check the internal links
diff --git a/.markdownlint.json b/.markdownlint.json
new file mode 100644
index 00000000000..2c40c0859f0
--- /dev/null
+++ b/.markdownlint.json
@@ -0,0 +1,31 @@
+{
+  "default": true,
+  "first-header-h1": true,
+  "header-style": {
+    "style": "atx"
+  },
+  "ul-style": {
+    "style": "dash"
+  },
+  "line-length": false,
+  "commands-show-output": false,
+  "no-duplicate-header": {
+    "allow_different_nesting": true
+  },
+  "no-trailing-punctuation": {
+    "punctuation": ".,;:!。，；：！？"
+  },
+  "ol-prefix": {
+    "style": "one"
+  },
+  "no-inline-html": false,
+  "hr-style": {
+    "style": "---"
+  },
+  "no-emphasis-as-heading": false,
+  "fenced-code-language": false,
+  "first-line-h1": false,
+  "code-block-style": {
+    "style": "fenced"
+  }
+}
diff --git a/.mdlrc b/.mdlrc
deleted file mode 100644
index 151c54f7d44..00000000000
--- a/.mdlrc
+++ /dev/null
@@ -1,7 +0,0 @@
-# This is the options file for mdl, configured in .gitlab/ci/docs.gitlab-ci.yml,
-# and related to the style file ./mdlrc.style
-
-# 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
deleted file mode 100644
index 85bc3aaa99b..00000000000
--- a/.mdlrc.style
+++ /dev/null
@@ -1,32 +0,0 @@
-# This is the style file for mdl, configured in .gitlab/ci/docs.gitlab-ci.yml,
-# and related to the options file ./mdlrc
-
-# See https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
-# for more detailed information on the rules and styles.
-
-rule "MD001"
-rule "MD002"
-rule "MD003", :style => :atx
-rule "MD006"
-rule "MD010"
-rule "MD011"
-rule "MD012"
-rule "MD019"
-rule "MD022"
-rule "MD023"
-rule "MD025"
-rule "MD028"
-rule "MD029", :style => :one
-rule "MD030"
-# rule "MD032"
-rule "MD034"
-rule "MD037"
-rule "MD038"
-
-# Should not be used currently:
-
-# rule "MD004", :style => :dash # unordered list style - dash
-# False positives, see https://github.com/markdownlint/markdownlint/issues/261
- 
-# rule "MD039" # Spaces inside link text
-# Crashes when link text has certain punctuation
diff --git a/danger/only_documentation/Dangerfile b/danger/only_documentation/Dangerfile
index dad12c0d29c..ce7ede26d9a 100644
--- a/danger/only_documentation/Dangerfile
+++ b/danger/only_documentation/Dangerfile
@@ -1,7 +1,7 @@
 # rubocop:disable Style/SignalException
 # frozen_string_literal: true
 
-has_only_docs_changes = helper.all_changed_files.all? { |file| file.start_with?('doc/', '.gitlab/ci/docs.gitlab-ci.yml', '.mdlrc') || file.end_with?('.md') }
+has_only_docs_changes = helper.all_changed_files.all? { |file| file.start_with?('doc/', '.gitlab/ci/docs.gitlab-ci.yml', '.markdownlint.json') || file.end_with?('.md') }
 is_docs_only_branch = gitlab.branch_for_head =~ /(^docs[\/-].*|.*-docs$)/
 
 if is_docs_only_branch && !has_only_docs_changes
diff --git a/doc/administration/smime_signing_email.md b/doc/administration/smime_signing_email.md
index 9f719088f25..b2e3bf8487b 100644
--- a/doc/administration/smime_signing_email.md
+++ b/doc/administration/smime_signing_email.md
@@ -22,7 +22,7 @@ email_smime:
 ```
 
 - Both files must be provided PEM-encoded.
-- The key file must be unencrypted so that Gitlab can read it without user 
+- The key file must be unencrypted so that Gitlab can read it without user
   intervention.
 
 NOTE: **Note:** Be mindful of the access levels for your private keys and visibility to
diff --git a/doc/development/emails.md b/doc/development/emails.md
index edec0f86989..5676c3b32f4 100644
--- a/doc/development/emails.md
+++ b/doc/development/emails.md
@@ -6,7 +6,7 @@ To view rendered emails "sent" in your development instance, visit
 [`/rails/letter_opener`](http://localhost:3000/rails/letter_opener).
 
 Please note that [S/MIME signed](../administration/smime_signing_email.md) emails
-[cannot be currently previewed](https://github.com/fgrehm/letter_opener_web/issues/96) with 
+[cannot be currently previewed](https://github.com/fgrehm/letter_opener_web/issues/96) with
 `letter_opener`.
 
 ## Mailer previews
diff --git a/doc/development/namespaces_storage_statistics.md b/doc/development/namespaces_storage_statistics.md
index b3285de4705..2c7e5935435 100644
--- a/doc/development/namespaces_storage_statistics.md
+++ b/doc/development/namespaces_storage_statistics.md
@@ -20,8 +20,8 @@ every time the project is saved.
 The summary of those statistics per namespace is then retrieved
 by [`Namespaces#with_statistics`](https://gitlab.com/gitlab-org/gitlab-ce/blob/v12.2.0.pre/app/models/namespace.rb#L70) scope. Analyzing this query we noticed that:
 
-* It takes up to `1.2` seconds for namespaces with over `15k` projects.
-* It can't be analyzed with [ChatOps](chatops_on_gitlabcom.md), as it times out.
+- It takes up to `1.2` seconds for namespaces with over `15k` projects.
+- It can't be analyzed with [ChatOps](chatops_on_gitlabcom.md), as it times out.
 
 Additionally, the pattern that is currently used to update the project statistics
 (the callback) doesn't scale adequately. It is currently one of the largest
@@ -62,8 +62,8 @@ REFRESH MATERIALIZED VIEW root_namespace_storage_statistics;
 
 While this implied a single query update (and probably a fast one), it has some downsides:
 
-* Materialized views syntax varies from PostgreSQL and MySQL. While this feature was worked on, MySQL was still supported by GitLab.
-* Rails does not have native support for materialized views. We'd need to use a specialized gem to take care of the management of the database views, which implies additional work.
+- Materialized views syntax varies from PostgreSQL and MySQL. While this feature was worked on, MySQL was still supported by GitLab.
+- Rails does not have native support for materialized views. We'd need to use a specialized gem to take care of the management of the database views, which implies additional work.
 
 ### Attempt B: An update through a CTE
 
@@ -131,8 +131,8 @@ WHERE namespace_id IN (
 
 Even though this approach would make aggregating much easier, it has some major downsides:
 
-* We'd have to migrate **all namespaces** by adding and filling a new column. Because of the size of the table, dealing with time/cost will not be great. The background migration will take approximately `153h`, see <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29772>.
-* Background migration has to be shipped one release before, delaying the functionality by another milestone.
+- We'd have to migrate **all namespaces** by adding and filling a new column. Because of the size of the table, dealing with time/cost will not be great. The background migration will take approximately `153h`, see <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/29772>.
+- Background migration has to be shipped one release before, delaying the functionality by another milestone.
 
 ### Attempt E (final): Update the namespace storage statistics in async way
 
@@ -155,10 +155,10 @@ but we refresh them through Sidekiq jobs and in different transactions:
 
 This implementation has the following benefits:
 
-* All the updates are done async, so we're not increasing the length of the transactions for `project_statistics`.
-* We're doing the update in a single SQL query.
-* It is compatible with PostgreSQL and MySQL.
-* No background migration required.
+- All the updates are done async, so we're not increasing the length of the transactions for `project_statistics`.
+- We're doing the update in a single SQL query.
+- It is compatible with PostgreSQL and MySQL.
+- No background migration required.
 
 The only downside of this approach is that namespaces' statistics are updated up to `1.5` hours after the change is done,
 which means there's a time window in which the statistics are inaccurate. Because we're still not
@@ -171,8 +171,8 @@ performant approach of aggregating the root namespaces.
 
 All the details regarding this use case can be found on:
 
-* <https://gitlab.com/gitlab-org/gitlab-ce/issues/62214>
-* Merge Request with the implementation: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28996>
+- <https://gitlab.com/gitlab-org/gitlab-ce/issues/62214>
+- Merge Request with the implementation: <https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28996>
 
 Performance of the namespace storage statistics were measured in staging and production (GitLab.com). All results were posted
 on <https://gitlab.com/gitlab-org/gitlab-ce/issues/64092>: No problem has been reported so far.
diff --git a/doc/development/uploads.md b/doc/development/uploads.md
index 234539bb673..681ce9d9fe8 100644
--- a/doc/development/uploads.md
+++ b/doc/development/uploads.md
@@ -174,14 +174,14 @@ sequenceDiagram
     c ->>+w: POST /some/url/upload
 
     w->>+s: save the incoming file on a temporary location
-    s-->>-w: 
+    s-->>-w:  
 
     w->>+r:  POST /some/url/upload
     Note over w,r: file was replaced with its location<br>and other metadata
 
     opt requires async processing
       r->>+redis: schedule a job
-      redis-->>-r: 
+      redis-->>-r:  
     end
 
     r-->>-c: request result
@@ -230,17 +230,17 @@ sequenceDiagram
 
     w->>+os: PUT file
     Note over w,os: file is stored on a temporary location. Rails select the destination
-    os-->>-w: 
+    os-->>-w:  
 
     w->>+r:  POST /some/url/upload
     Note over w,r: file was replaced with its location<br>and other metadata
 
     r->>+os: move object to final destination
-    os-->>-r: 
+    os-->>-r:  
 
     opt requires async processing
       r->>+redis: schedule a job
-      redis-->>-r: 
+      redis-->>-r:  
     end
 
     r-->>-c: request result
@@ -268,4 +268,3 @@ sequenceDiagram
 This option affect the response to the `/authorize` call. When not enabled, the API response will not contain presigned URLs and workhorse will write the file the shared disk, on the path is provided by rails, acting like object storage was disabled.
 
 Once the request reachs rails, it will schedule an object storage upload as a sidekiq job.
-
diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md
index 5de173abbff..a289b90b81b 100644
--- a/doc/gitlab-basics/start-using-git.md
+++ b/doc/gitlab-basics/start-using-git.md
@@ -102,7 +102,7 @@ files to your local computer, automatically preserving the Git connection with t
 remote repository.
 
 You can either clone it via HTTPS or [SSH](../ssh/README.md). If you chose to clone
-it via HTTPS, you'll have to enter your credentials every time you pull and push. You can read more about credential storage in the [Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). With SSH, you enter your credentials only once. 
+it via HTTPS, you'll have to enter your credentials every time you pull and push. You can read more about credential storage in the [Git Credentials documentation](https://git-scm.com/book/en/v2/Git-Tools-Credential-Storage). With SSH, you enter your credentials only once.
 
 You can find both paths (HTTPS and SSH) by navigating to your project's landing page
 and clicking **Clone**. GitLab will prompt you with both paths, from which you can copy
@@ -157,7 +157,7 @@ git pull <REMOTE> <name-of-branch>
 When you clone a repository, `REMOTE` is typically `origin`. This is where the
 repository was cloned from, and it indicates the SSH or HTTPS URL of the repository
 on the remote server. `<name-of-branch>` is usually `master`, but it may be any existing
-branch. You can create additional named remotes and branches as necessary. 
+branch. You can create additional named remotes and branches as necessary.
 
 You can learn more on how Git manages remote repositories in the [Git Remote documentation](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes).
 
@@ -169,7 +169,7 @@ To view your remote repositories, type:
 git remote -v
 ```
 
-The `-v` flag stands for verbose. 
+The `-v` flag stands for verbose.
 
 ### Add a remote repository