Refactor Markdownlint configuration

.gitlab/ci/rules.gitlab-ci.yml

@@ -124,7 +124,7 @@
 .docs-patterns: &docs-patterns
   - ".gitlab/route-map.yml"
   - "doc/**/*"
-  - ".markdownlint.json"
+  - ".markdownlint.yml"
   - "scripts/lint-doc.sh"
 
 .frontend-dependency-patterns: &frontend-dependency-patterns

.markdownlint.json

-{
-  "default": true,
-  "first-header-h1": true,
-  "header-style": {
-    "style": "atx"
-  },
-  "ul-style": {
-    "style": "dash"
-  },
-  "no-trailing-spaces": false,
-  "line-length": 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,
-  "first-line-h1": false,
-  "code-block-style": {
-    "style": "fenced"
-  },
-  "proper-names": {
-    "names": [
-      "Akismet",
-      "Alertmanager",
-      "API",
-      "Asana",
-      "Auth0",
-      "Authentiq",
-      "Azure",
-      "Bamboo",
-      "Bitbucket",
-      "Bugzilla",
-      "CAS",
-      "CentOS",
-      "Consul",
-      "Debian",
-      "DevOps",
-      "Docker",
-      "DockerSlim",
-      "Elasticsearch",
-      "Facebook",
-      "fastlane",
-      "fluent-plugin-redis-slowlog",
-      "GDK",
-      "Geo",
-      "Git LFS",
-      "git-annex",
-      "Git",
-      "Gitaly",
-      "GitHub",
-      "GitLab Geo",
-      "GitLab Monitor",
-      "GitLab Operator",
-      "GitLab Pages",
-      "GitLab Rails",
-      "GitLab Runner",
-      "GitLab Shell",
-      "GitLab Workhorse",
-      "GitLab",
-      "Gitleaks",
-      "Gmail",
-      "Google",
-      "Grafana",
-      "Gzip",
-      "Helm",
-      "HipChat",
-      "ID",
-      "Ingress",
-      "jasmine-jquery",
-      "JavaScript",
-      "Jaeger",
-      "Jenkins",
-      "Jira",
-      "Jira Cloud",
-      "Jira Server",
-      "jQuery",
-      "JSON",
-      "JupyterHub",
-      "Karma",
-      "Kerberos",
-      "Knative",
-      "Kubernetes",
-      "LDAP",
-      "Let's Encrypt",
-      "Markdown",
-      "markdownlint",
-      "Mattermost",
-      "Microsoft",
-      "Minikube",
-      "MinIO",
-      "ModSecurity",
-      "NGINX Ingress",
-      "NGINX",
-      "OAuth",
-      "OAuth 2",
-      "OmniAuth",
-      "Omnibus GitLab",
-      "OpenID",
-      "OpenShift",
-      "PgBouncer",
-      "PostgreSQL",
-      "Praefect",
-      "Prometheus",
-      "Puma",
-      "puma-worker-killer",
-      "Python",
-      "Rake",
-      "Redis",
-      "Redmine",
-      "reCAPTCHA",
-      "Ruby",
-      "runit",
-      "Salesforce",
-      "SAML",
-      "Sentry",
-      "Sidekiq",
-      "Shibboleth",
-      "Slack",
-      "SMTP",
-      "SpotBugs",
-      "SSH",
-      "Tiller",
-      "TOML",
-      "Trello",
-      "Trello Power-Ups",
-      "TypeScript",
-      "Twitter",
-      "Ubuntu",
-      "Ultra Auth",
-      "Unicorn",
-      "unicorn-worker-killer",
-      "URL",
-      "WebdriverIO",
-      "YAML",
-      "YouTrack"
-    ],
-    "code_blocks": false
-  }
-}

.markdownlint.yml

+# Base Markdownlint configuration
+# Extended Markdownlint configuration in doc/.markdownlint/
+"default": true
+"first-header-h1": true
+"header-style":
+  "style": "atx"
+"ul-style":
+  "style": "dash"
+"no-trailing-spaces": false
+"line-length": 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
+"first-line-h1": false
+"code-block-style":
+  "style": "fenced"
+"proper-names":
+  "names": [
+    "Akismet",
+    "Alertmanager",
+    "API",
+    "Asana",
+    "Auth0",
+    "Authentiq",
+    "Azure",
+    "Bamboo",
+    "Bitbucket",
+    "Bugzilla",
+    "CAS",
+    "CentOS",
+    "Consul",
+    "Debian",
+    "DevOps",
+    "Docker",
+    "DockerSlim",
+    "Elasticsearch",
+    "Facebook",
+    "fastlane",
+    "fluent-plugin-redis-slowlog",
+    "GDK",
+    "Geo",
+    "Git LFS",
+    "git-annex",
+    "Git",
+    "Gitaly",
+    "GitHub",
+    "GitLab Geo",
+    "GitLab Monitor",
+    "GitLab Operator",
+    "GitLab Pages",
+    "GitLab Rails",
+    "GitLab Runner",
+    "GitLab Shell",
+    "GitLab Workhorse",
+    "GitLab",
+    "Gitleaks",
+    "Gmail",
+    "Google",
+    "Grafana",
+    "Gzip",
+    "Helm",
+    "HipChat",
+    "ID",
+    "Ingress",
+    "jasmine-jquery",
+    "JavaScript",
+    "Jaeger",
+    "Jenkins",
+    "Jira",
+    "Jira Cloud",
+    "Jira Server",
+    "jQuery",
+    "JSON",
+    "JupyterHub",
+    "Karma",
+    "Kerberos",
+    "Knative",
+    "Kubernetes",
+    "LDAP",
+    "Let's Encrypt",
+    "Markdown",
+    "markdownlint",
+    "Mattermost",
+    "Microsoft",
+    "Minikube",
+    "MinIO",
+    "ModSecurity",
+    "NGINX Ingress",
+    "NGINX",
+    "OAuth",
+    "OAuth 2",
+    "OmniAuth",
+    "Omnibus GitLab",
+    "OpenID",
+    "OpenShift",
+    "PgBouncer",
+    "PostgreSQL",
+    "Praefect",
+    "Prometheus",
+    "Puma",
+    "puma-worker-killer",
+    "Python",
+    "Rake",
+    "Redis",
+    "Redmine",
+    "reCAPTCHA",
+    "Ruby",
+    "runit",
+    "Salesforce",
+    "SAML",
+    "Sentry",
+    "Sidekiq",
+    "Shibboleth",
+    "Slack",
+    "SMTP",
+    "SpotBugs",
+    "SSH",
+    "Tiller",
+    "TOML",
+    "Trello",
+    "Trello Power-Ups",
+    "TypeScript",
+    "Twitter",
+    "Ubuntu",
+    "Ultra Auth",
+    "Unicorn",
+    "unicorn-worker-killer",
+    "URL",
+    "WebdriverIO",
+    "YAML",
+    "YouTrack"
+  ]
+  "code_blocks": false

.overcommit.yml.example

@@ -48,7 +48,7 @@ PreCommit:
     enabled: true
     description: 'Lint documentation for Markdown errors'
     required_executable: 'node_modules/.bin/markdownlint'
-    flags: ['--config', '.markdownlint.json', 'doc/**/*.md']
+    flags: ['--config', '.markdownlint.yml', 'doc/**/*.md']
     install_command: 'yarn install'
     include:
       - 'doc/**/*.md'

doc/.markdownlint/markdownlint-no-trailing-spaces.yml

+# Extended Markdown configuration to enforce no-trailing-spaces rule
+"extends": "../../.markdownlint.yml"
+"no-trailing-spaces": true

doc/development/documentation/styleguide/index.md

@@ -164,13 +164,12 @@ standard for GitLab documentation).
 
 A rule that could cause confusion is `MD044/proper-names`, as it might not be
 immediately clear what caused markdownlint to fail, or how to correct the
-failure. This rule checks a list of known words, listed in the `.markdownlint.json`
+failure. This rule checks a list of known words, listed in the `.markdownlint.yml`
 file in each project, to verify proper use of capitalization and backticks.
 Words in backticks are ignored by markdownlint.
 
 In general, product names should follow the exact capitalization of the official
-names of the products, protocols, and so on. See [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json)
-for the words tested for proper capitalization in GitLab documentation.
+names of the products, protocols, and so on.
 
 Some examples fail if incorrect capitalization is used:
 
@@ -370,7 +369,7 @@ Capitalize names of:
 - Third-party organizations, software, and products. For example, Prometheus,
   Kubernetes, Git, and The Linux Foundation.
 - Methods or methodologies. For example, Continuous Integration,
-  Continuous Deployment, Scrum, and Agile. (Tested in [`.markdownlint.json`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.markdownlint.json).)
+  Continuous Deployment, Scrum, and Agile.
 
 Follow the capitalization style listed at the [authoritative source](#links-to-external-documentation)
 for the entity, which may use non-standard case styles. For example: GitLab and

doc/development/documentation/testing.md

@@ -150,11 +150,11 @@ from those guidelines.
 
 markdownlint configuration is found in the following projects:
 
-- [`gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/.markdownlint.json)
-- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner/blob/master/.markdownlint.json)
-- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/.markdownlint.json)
-- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/.markdownlint.json)
-- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/.markdownlint.json)
+- [`gitlab`](https://gitlab.com/gitlab-org/gitlab)
+- [`gitlab-runner`](https://gitlab.com/gitlab-org/gitlab-runner)
+- [`omnibus-gitlab`](https://gitlab.com/gitlab-org/omnibus-gitlab)
+- [`charts`](https://gitlab.com/gitlab-org/charts/gitlab)
+- [`gitlab-development-kit`](https://gitlab.com/gitlab-org/gitlab-development-kit)
 
 This configuration is also used in build pipelines.
 

package.json

@@ -33,7 +33,9 @@
     "lint:stylelint:fix": "yarn run lint:stylelint --fix",
     "lint:stylelint:staged": "scripts/frontend/execute-on-staged-files.sh stylelint '(css|scss)' -q",
     "lint:stylelint:staged:fix": "yarn run lint:stylelint:staged --fix",
-    "markdownlint": "markdownlint --config .markdownlint.json",
+    "markdownlint": "markdownlint --config .markdownlint.yml",
+    "markdownlint:no-trailing-spaces": "markdownlint --config doc/.markdownlint/markdownlint-no-trailing-spaces.yml",
+    "markdownlint:no-trailing-spaces:fix": "yarn run markdownlint:no-trailing-spaces --fix",
     "postinstall": "node ./scripts/frontend/postinstall.js",
     "stylelint-create-utility-map": "node scripts/frontend/stylelint/stylelint-utility-map.js",
     "webpack": "NODE_OPTIONS=\"--max-old-space-size=3584\" webpack --config config/webpack.config.js",

scripts/lint-doc.sh

@@ -137,7 +137,7 @@ if [ -z "${MD_DOC_PATH}" ]
 then
   echo "Merged results pipeline detected, but no markdown files found. Skipping."
 else
-  run_locally_or_in_docker 'markdownlint' "--config .markdownlint.json ${MD_DOC_PATH}"
+  run_locally_or_in_docker 'markdownlint' "--config .markdownlint.yml ${MD_DOC_PATH}"
 fi
 
 echo '=> Linting prose...'