Merge branch 'docs-capitalization-lint-1' into 'master'

Add caps and backtick testing to docs linting

Closes #31185

See merge request gitlab-org/gitlab!20764

.markdownlint.json

@@ -26,5 +26,103 @@
   "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",
+      "Elasticsearch",
+      "Facebook",
+      "Git LFS",
+      "git-annex",
+      "gitlab-ui",
+      "Git",
+      "Gitaly",
+      "GitHub",
+      "GitLab Geo",
+      "GitLab Monitor",
+      "GitLab Operator",
+      "GitLab Pages",
+      "GitLab Rails",
+      "GitLab Runner",
+      "GitLab Shell",
+      "GitLab Workhorse",
+      "GitLab",
+      "Gmail",
+      "Google",
+      "Grafana",
+      "Helm",
+      "HipChat",
+      "Ingress",
+      "jasmine-jquery",
+      "JavaScript",
+      "Jaeger",
+      "Jenkins",
+      "Jira",
+      "Jira Cloud",
+      "Jira Server",
+      "jQuery",
+      "JupyterHub",
+      "Karma",
+      "Kerberos",
+      "Knative",
+      "Kubernetes",
+      "LDAP",
+      "Let's Encrypt",
+      "Markdown",
+      "markdownlint",
+      "Mattermost",
+      "Microsoft",
+      "MinIO",
+      "NGINX Ingress",
+      "NGINX",
+      "OAuth",
+      "OAuth 2",
+      "OmniAuth",
+      "Omnibus GitLab",
+      "OpenID",
+      "OpenShift",
+      "PgBouncer",
+      "PostgreSQL",
+      "Prometheus",
+      "Puma",
+      "Python",
+      "Redis",
+      "Redmine",
+      "reCAPTCHA",
+      "runit",
+      "Salesforce",
+      "SAML",
+      "Sentry",
+      "Sidekiq",
+      "Shibboleth",
+      "Slack",
+      "SMTP",
+      "SSH",
+      "Tiller",
+      "Trello",
+      "Trello Power-Ups",
+      "TypeScript",
+      "Twitter",
+      "Ubuntu",
+      "Ultra Auth",
+      "Unicorn",
+      "unicorn-worker-killer",
+      "WebdriverIO",
+      "YouTrack"
+    ],
+    "code_blocks": false
   }
 }

app/graphql/types/label_type.rb

@@ -9,7 +9,7 @@ module Types
     field :id, GraphQL::ID_TYPE, null: false,
           description: 'Label ID'
     field :description, GraphQL::STRING_TYPE, null: true,
-          description: 'Description of the label (markdown rendered as HTML for caching)'
+          description: 'Description of the label (Markdown rendered as HTML for caching)'
     markdown_field :description_html, null: true
     field :title, GraphQL::STRING_TYPE, null: false,
           description: 'Content of the label'

app/graphql/types/merge_request_type.rb

@@ -20,7 +20,7 @@ module Types
           description: 'Title of the merge request'
     markdown_field :title_html, null: true
     field :description, GraphQL::STRING_TYPE, null: true,
-          description: 'Description of the merge request (markdown rendered as HTML for caching)'
+          description: 'Description of the merge request (Markdown rendered as HTML for caching)'
     markdown_field :description_html, null: true
     field :state, MergeRequestStateEnum, null: false,
           description: 'State of the merge request'

app/graphql/types/root_storage_statistics_type.rb

@@ -7,7 +7,7 @@ module Types
     authorize :read_statistics
 
     field :storage_size, GraphQL::INT_TYPE, null: false, description: 'The total storage in bytes'
-    field :repository_size, GraphQL::INT_TYPE, null: false, description: 'The git repository size in bytes'
+    field :repository_size, GraphQL::INT_TYPE, null: false, description: 'The Git repository size in bytes'
     field :lfs_objects_size, GraphQL::INT_TYPE, null: false, description: 'The LFS objects size in bytes'
     field :build_artifacts_size, GraphQL::INT_TYPE, null: false, description: 'The CI artifacts size in bytes'
     field :packages_size, GraphQL::INT_TYPE, null: false, description: 'The packages size in bytes'

doc/api/graphql/reference/gitlab_schema.graphql

@@ -2815,7 +2815,7 @@ type Label {
   color: String!
 
   """
-  Description of the label (markdown rendered as HTML for caching)
+  Description of the label (Markdown rendered as HTML for caching)
   """
   description: String
 
@@ -2917,7 +2917,7 @@ type MergeRequest implements Noteable {
   defaultMergeCommitMessage: String
 
   """
-  Description of the merge request (markdown rendered as HTML for caching)
+  Description of the merge request (Markdown rendered as HTML for caching)
   """
   description: String
 
@@ -5112,7 +5112,7 @@ type RootStorageStatistics {
   packagesSize: Int!
 
   """
-  The git repository size in bytes
+  The Git repository size in bytes
   """
   repositorySize: Int!
 

doc/api/graphql/reference/gitlab_schema.json

@@ -2647,7 +2647,7 @@
             },
             {
               "name": "repositorySize",
-              "description": "The git repository size in bytes",
+              "description": "The Git repository size in bytes",
               "args": [
 
               ],
@@ -7591,7 +7591,7 @@
             },
             {
               "name": "description",
-              "description": "Description of the label (markdown rendered as HTML for caching)",
+              "description": "Description of the label (Markdown rendered as HTML for caching)",
               "args": [
 
               ],
@@ -13656,7 +13656,7 @@
             },
             {
               "name": "description",
-              "description": "Description of the merge request (markdown rendered as HTML for caching)",
+              "description": "Description of the merge request (Markdown rendered as HTML for caching)",
               "args": [
 
               ],

doc/api/graphql/reference/index.md

@@ -399,7 +399,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `id` | ID! | Label ID |
-| `description` | String | Description of the label (markdown rendered as HTML for caching) |
+| `description` | String | Description of the label (Markdown rendered as HTML for caching) |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `title` | String! | Content of the label |
 | `color` | String! | Background color of the label |
@@ -414,7 +414,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | `iid` | String! | Internal ID of the merge request |
 | `title` | String! | Title of the merge request |
 | `titleHtml` | String | The GitLab Flavored Markdown rendering of `title` |
-| `description` | String | Description of the merge request (markdown rendered as HTML for caching) |
+| `description` | String | Description of the merge request (Markdown rendered as HTML for caching) |
 | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` |
 | `state` | MergeRequestState! | State of the merge request |
 | `createdAt` | Time! | Timestamp of when the merge request was created |
@@ -749,7 +749,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph
 | Name  | Type  | Description |
 | ---   |  ---- | ----------  |
 | `storageSize` | Int! | The total storage in bytes |
-| `repositorySize` | Int! | The git repository size in bytes |
+| `repositorySize` | Int! | The Git repository size in bytes |
 | `lfsObjectsSize` | Int! | The LFS objects size in bytes |
 | `buildArtifactsSize` | Int! | The CI artifacts size in bytes |
 | `packagesSize` | Int! | The packages size in bytes |

doc/ci/environments.md

@@ -335,7 +335,7 @@ deploy:
 NOTE: **Note:**
 Kubernetes configuration is not supported for Kubernetes clusters
 that are [managed by GitLab](../user/project/clusters/index.md#gitlab-managed-clusters).
-To follow progress on support for Gitlab-managed clusters, see the
+To follow progress on support for GitLab-managed clusters, see the
 [relevant issue](https://gitlab.com/gitlab-org/gitlab/issues/38054).
 
 ### Complete example

doc/ci/yaml/README.md

@@ -1456,7 +1456,7 @@ For more information, see
 NOTE: **Note:**
 Kubernetes configuration is not supported for Kubernetes clusters
 that are [managed by GitLab](../../user/project/clusters/index.md#gitlab-managed-clusters).
-To follow progress on support for Gitlab-managed clusters, see the
+To follow progress on support for GitLab-managed clusters, see the
 [relevant issue](https://gitlab.com/gitlab-org/gitlab/issues/38054).
 
 #### Dynamic environments

doc/development/documentation/index.md

@@ -399,7 +399,7 @@ merge request with new or changed docs is submitted, are:
     - The `CHANGELOG.md` does not contain duplicate versions.
     - No files in `doc/` are executable.
     - No new `README.md` was added.
-  - [`markdownlint`](#markdownlint).
+  - [markdownlint](#markdownlint).
   - Nanoc tests, which you can [run locally](#previewing-the-changes-live) before
     pushing to GitLab by executing the command `bundle exec nanoc check internal_links`
     (or `internal_anchors`) on your local [`gitlab-docs`](https://gitlab.com/gitlab-org/gitlab-docs) directory:
@@ -420,7 +420,7 @@ help you catch common issues before raising merge requests for review of documen
 The following are some suggested linters you can install locally and sample configuration:
 
 - [`proselint`](#proselint)
-- [`markdownlint`](#markdownlint), which is the same as the test run in [`docs-lint`](#testing)
+- [markdownlint](#markdownlint), which is the same as the test run in [`docs-lint`](#testing)
 
 NOTE: **Note:**
 This list does not limit what other linters you can add to your local documentation writing toolchain.
@@ -464,18 +464,18 @@ noise. The following sample `proselint` configuration disables these checks:
 A file with `proselint` configuration must be placed in a
 [valid location](https://github.com/amperser/proselint#checks). For example, `~/.config/proselint/config`.
 
-#### `markdownlint`
+#### markdownlint
 
-[`markdownlint`](https://github.com/DavidAnson/markdownlint) checks that Markdown
+[markdownlint](https://github.com/DavidAnson/markdownlint) checks that Markdown
 syntax follows [certain rules](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules),
 and is used by the [`docs-lint` test](#testing) with a [configuration file](#markdownlint-configuration).
 Our [Documentation Style Guide](styleguide.md#markdown) and [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/)
 elaborate on which choices must be made when selecting Markdown syntax for GitLab
 documentation. This tool helps catch deviations from those guidelines.
 
-`markdownlint` can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
+markdownlint can be used [on the command line](https://github.com/igorshubovych/markdownlint-cli#markdownlint-cli--),
 either on a single Markdown file or on all Markdown files in a project. For example, to run
-`markdownlint` on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab),
+markdownlint on all documentation in the [`gitlab` project](https://gitlab.com/gitlab-org/gitlab),
 run the following commands from within your `gitlab` project root directory, which will
 automatically detect the [`.markdownlint.json`](#markdownlint-configuration) config
 file in the root of the project, and test all files in `/doc` and its subdirectories:
@@ -490,7 +490,7 @@ If you wish to use a different config file, use the `-c` flag:
 markdownlint -c <config-file-name> 'doc/**/*.md'
 ```
 
-`markdownlint` can also be run from within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related),
+markdownlint can also be run from within text editors using [plugins/extensions](https://github.com/DavidAnson/markdownlint#related),
 such as:
 
 - [Sublime Text](https://packagecontrol.io/packages/SublimeLinter-contrib-markdownlint)
@@ -502,9 +502,9 @@ is in use in the four repos that are the sources for <https://docs.gitlab.com>.
 plugin/extension has different requirements regarding the configuration file, which
 is explained in each editor's docs.
 
-##### `markdownlint` configuration
+##### markdownlint configuration
 
-Each formatting issue that `markdownlint` checks has an associated
+Each formatting issue that markdownlint checks has an associated
 [rule](https://github.com/DavidAnson/markdownlint/blob/master/doc/Rules.md#rules).
 These rules are configured in the `.markdownlint.json` files located in the root of
 four repos that are the sources for <https://docs.gitlab.com>:
@@ -518,7 +518,7 @@ By default all rules are enabled, so the configuration file is used to disable u
 rules, and also to configure optional parameters for enabled rules as needed. You can
 also check [the issue](https://gitlab.com/gitlab-org/gitlab-foss/issues/64352) that
 tracked the changes required to implement these rules, and details which rules were
-on or off when `markdownlint` was enabled on the docs.
+on or off when markdownlint was enabled on the docs.
 
 ## Danger Bot
 

doc/development/documentation/styleguide.md

@@ -111,11 +111,38 @@ Hard-coded HTML is valid, although it's discouraged to be used while we have `/h
 
 GitLab ensures that the Markdown used across all documentation is consistent, as
 well as easy to review and maintain, by [testing documentation changes](index.md#testing) with
-[`markdownlint`](index.md#markdownlint). This lint test fails when any document has an issue
+[markdownlint](index.md#markdownlint). This lint test fails when any document has an issue
 with Markdown formatting that may cause the page to render incorrectly within GitLab.
 It will also fail when a document is using non-standard Markdown (which may render
 correctly, but is not the current standard for GitLab documentation).
 
+#### Markdown rule `MD044/proper-names` (capitalization)
+
+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` file in each project,
+to verify that proper capitalization and backticks are used. Words in backticks will
+be ignored by markdownlint.
+
+In general, product names should follow the exact capitalization of the official names
+of the products, protocols, etc.
+
+Some examples that will fail if incorrect capitalization is used:
+
+- MinIO (needs capital `IO`)
+- NGINX (needs all capitals)
+- runit (needs lowercase `r`)
+
+Additionally, commands, parameters, values, filenames, etc. must be included in backticks.
+For example:
+
+- "Change the `needs` keyword in your `.gitlab.yml`..."
+  - `needs` is a parameter, and `.gitlab.yml` is a file, so both need backticks. Additionally,
+    `.gitlab.yml` will fail markdownlint without backticks as it does not have capital G or L.
+- "Run `git clone` to clone a Git repository..."
+  - `git clone` is a command, so it must be lowercase, while Git is the product, so
+    it must have a capital G.
+
 ## Structure
 
 ### Organize by topic, not by type

doc/development/fe_guide/style/scss.md

@@ -11,7 +11,7 @@ easy to maintain, and performant for the end-user.
 
 ### Utility Classes
 
-As part of the effort for [cleaning up our CSS and moving our components into GitLab-UI](https://gitlab.com/groups/gitlab-org/-/epics/950)
+As part of the effort for [cleaning up our CSS and moving our components into gitlab-ui](https://gitlab.com/groups/gitlab-org/-/epics/950)
 led by the [GitLab UI WG](https://gitlab.com/gitlab-com/www-gitlab-com/merge_requests/20623) we prefer the use of utility classes over adding new CSS. However, complex CSS can be addressed by adding component classes.
 
 #### Where are utility classes defined?

doc/development/fe_guide/tooling.md

@@ -2,7 +2,7 @@
 
 ## ESLint
 
-We use ESLint to encapsulate and enforce frontend code standards. Our configuration may be found in the [gitlab-eslint-config](https://gitlab.com/gitlab-org/gitlab-eslint-config) project.
+We use ESLint to encapsulate and enforce frontend code standards. Our configuration may be found in the [`gitlab-eslint-config`](https://gitlab.com/gitlab-org/gitlab-eslint-config) project.
 
 ### Disabling ESLint in new files
 

doc/integration/jenkins.md

@@ -138,7 +138,7 @@ configured or there was an error reporting the status via the API.
 
 ### Merge Request event does not trigger a Jenkins Pipeline
 
-Check the **/var/log/gitlab/gitlab-rails/production.log** file for messages like:
+Check the `/var/log/gitlab/gitlab-rails/production.log` file for messages like:
 
 ```plaintext
 WebHook Error => Net::ReadTimeout
@@ -157,7 +157,7 @@ which is set to 10 seconds by default.
 To fix this the `gitlab_rails['webhook_timeout']` value will need to be increased
 in the `gitlab.rb` config file, followed by the [`gitlab-ctl reconfigure` command](../administration/restart_gitlab.md).
 
-If you don't find the errors above, but do find *duplicate* entries like below (in **/var/log/gitlab/gitlab-rail**), this
+If you don't find the errors above, but do find *duplicate* entries like below (in `/var/log/gitlab/gitlab-rail`), this
 could also indicate that [webhook requests are timing out](../user/project/integrations/webhooks.md#receiving-duplicate-or-multiple-webhook-requests-triggered-by-one-event):
 
 ```

doc/integration/vault.md

@@ -19,7 +19,7 @@ The following assumes you already have Vault installed and running.
 
     1. On GitLab, click your avatar on the top-right corner, and select your user **Settings > Applications**.
     1. Fill out the application **Name** and [**Redirect URI**](https://www.vaultproject.io/docs/auth/jwt.html#redirect-uris),
-    making sure to select the **openid** scope.
+       making sure to select the **OpenID** scope.
     1. Save application.
     1. Copy client ID and secret, or keep the page open for reference.
     ![GitLab OAuth provider](img/gitlab_oauth_vault_v12_6.png)
@@ -42,7 +42,7 @@ The following assumes you already have Vault installed and running.
 
 1. **Write the OIDC config:**
 
-    Next, Vault needs to be given the application ID and secret generated by Gitlab.
+    Next, Vault needs to be given the application ID and secret generated by GitLab.
 
     In the terminal session, run the following command to give Vault access to the GitLab application you've just created with an OpenID scope. This allows Vault to authenticate through GitLab.
 

doc/user/clusters/applications.md

@@ -481,7 +481,7 @@ applications you have configured.
 
 ### Install Ingress using GitLab CI
 
-To install ingress, define the `.gitlab/managed-apps/config.yaml` file
+To install Ingress, define the `.gitlab/managed-apps/config.yaml` file
 with:
 
 ```yaml

doc/user/project/repository/repository_mirroring.md

@@ -408,8 +408,8 @@ Note that this sample has a few limitations:
   - It does not regard different types of authentication mechanisms for the mirror.
   - It does not work with forced updates (rewriting history).
   - Only branches that match the `whitelisted` patterns will be proxy pushed.
-- The script circumvents the git hook quarantine environment because the update of `$TARGET_REPO`
-  is seen as a ref update and git will complain about it.
+- The script circumvents the Git hook quarantine environment because the update of `$TARGET_REPO`
+  is seen as a ref update and Git will complain about it.
 
 ### Mirroring with Perforce Helix via Git Fusion **(STARTER)**