Merge branch 'docs-mdl-rules-update-2' into 'master'

Add more rules to markdown lint check

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

18 files changed, 186 insertions, 250 deletions

diff --git a/.mdlrc.style b/.mdlrc.style
index 36fbba3543b..b315c99e3fc 100644
--- a/.mdlrc.style
+++ b/.mdlrc.style
@@ -8,12 +8,16 @@ 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"
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md
index 78d040cda99..3445f916ef4 100644
--- a/doc/administration/auth/oidc.md
+++ b/doc/administration/auth/oidc.md
@@ -74,43 +74,38 @@ The OpenID Connect will provide you with a client details and secret for you to
        }
    ```
 
-   > **Note:**
-   >
-   > - For more information on each configuration option refer to
-       the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage) and
-       the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
+   NOTE: **Note:**
+   For more information on each configuration option refer to the [OmniAuth OpenID Connect usage documentation](https://github.com/m0n9oose/omniauth_openid_connect#usage)
+   and the [OpenID Connect Core 1.0 specification](https://openid.net/specs/openid-connect-core-1_0.html).
 
 1. For the configuration above, change the values for the provider to match your OpenID Connect client setup. Use the following as a guide:
-    - `<your_oidc_label>` is the label that will be displayed on the login page.
-    - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`.
-      If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`.
-    - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`.
-    - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider.
-      - Supported values are:
-        - `basic` - HTTP Basic Authentication
-        - `jwt_bearer` - JWT based authentication (private key and client secret signing)
-        - `mtls` - Mutual TLS or X.509 certificate validation
-        - Any other value will POST the client id and secret in the request body
-      - If not specified, defaults to `basic`.
-    - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
-      If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
-    - `client_options` are the OpenID Connect client-specific options. Specifically:
-
-      - `identifier` is the client identifier as configured in the OpenID Connect service provider.
-      - `secret` is the client secret as configured in the OpenID Connect service provider.
-      - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`.
-      - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
-
-      The following `client_options` are optional unless auto-discovery is disabled or unsuccessful:
-
-        - `authorization_endpoint` is the URL to the endpoint that authorizes the end user.
-        - `token_endpoint` is the URL to the endpoint that provides Access Token.
-        - `userinfo_endpoint` is the URL to the endpoint that provides the user information.
-        - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys.
-
-1.  Save the configuration file.
-1.  [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source)
-    for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
+   - `<your_oidc_label>` is the label that will be displayed on the login page.
+   - `<your_oidc_url>` (optional) is the URL that points to the OpenID Connect provider. For example, `https://example.com/auth/realms/your-realm`.
+     If this value is not provided, the URL is constructed from the `client_options` in the following format: `<client_options.scheme>://<client_options.host>:<client_options.port>`.
+   - If `discovery` is set to `true`, the OpenID Connect provider will try to auto discover the client options using `<your_oidc_url>/.well-known/openid-configuration`. Defaults to `false`.
+   - `client_auth_method` (optional) specifies the method used for authenticating the client with the OpenID Connect provider.
+     - Supported values are:
+       - `basic` - HTTP Basic Authentication
+       - `jwt_bearer` - JWT based authentication (private key and client secret signing)
+       - `mtls` - Mutual TLS or X.509 certificate validation
+       - Any other value will POST the client id and secret in the request body
+     - If not specified, defaults to `basic`.
+   - `<uid_field>` (optional) is the field name from the `user_info` details that will be used as `uid` value. For example, `preferred_username`.
+     If this value is not provided or the field with the configured value is missing from the `user_info` details, the `uid` will use the `sub` field.
+   - `client_options` are the OpenID Connect client-specific options. Specifically:
+     - `identifier` is the client identifier as configured in the OpenID Connect service provider.
+     - `secret` is the client secret as configured in the OpenID Connect service provider.
+     - `redirect_uri` is the GitLab URL to redirect the user to after successful login. For example, `http://example.com/users/auth/openid_connect/callback`.
+     - `end_session_endpoint` (optional) is the URL to the endpoint that end the session (logout). Can be provided if auto-discovery disabled or unsuccessful.
+     - The following `client_options` are optional unless auto-discovery is disabled or unsuccessful:
+       - `authorization_endpoint` is the URL to the endpoint that authorizes the end user.
+       - `token_endpoint` is the URL to the endpoint that provides Access Token.
+       - `userinfo_endpoint` is the URL to the endpoint that provides the user information.
+       - `jwks_uri` is the URL to the endpoint where the Token signer publishes its keys.
+
+1. Save the configuration file.
+1. [Reconfigure](../restart_gitlab.md#omnibus-gitlab-reconfigure) or [restart GitLab](../restart_gitlab.md#installations-from-source)
+   for the changes to take effect if you installed GitLab via Omnibus or from source respectively.
 
 On the sign in page, there should now be an OpenID Connect icon below the regular sign in form.
 Click the icon to begin the authentication process. The OpenID Connect provider will ask the user to
diff --git a/doc/administration/container_registry.md b/doc/administration/container_registry.md
index 3e3054af509..e418938451a 100644
--- a/doc/administration/container_registry.md
+++ b/doc/administration/container_registry.md
@@ -27,8 +27,6 @@ but not recommended and out of the scope of this document.
 Read the [insecure Registry documentation][docker-insecure] if you want to
 implement this.
 
----
-
 **Installations from source**
 
 If you have installed GitLab from source:
@@ -116,8 +114,6 @@ GitLab from source respectively.
 Be careful to choose a port different than the one that Registry listens to (`5000` by default),
 otherwise you will run into conflicts.
 
----
-
 **Omnibus GitLab installations**
 
 1. Your `/etc/gitlab/gitlab.rb` should contain the Registry URL as well as the
@@ -141,8 +137,6 @@ otherwise you will run into conflicts.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
@@ -158,8 +152,6 @@ otherwise you will run into conflicts.
 1. Save the file and [restart GitLab][] for the changes to take effect.
 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
 
----
-
 Users should now be able to login to the Container Registry with their GitLab
 credentials using:
 
@@ -177,8 +169,6 @@ domain (e.g., `registry.gitlab.example.com`).
 Let's assume that you want the container Registry to be accessible at
 `https://registry.gitlab.example.com`.
 
----
-
 **Omnibus GitLab installations**
 
 1. Place your TLS certificate and key in
@@ -210,8 +200,6 @@ look like:
 > registry_nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/certificate.key"
 > ```
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
@@ -226,8 +214,6 @@ look like:
 1. Save the file and [restart GitLab][] for the changes to take effect.
 1. Make the relevant changes in NGINX as well (domain, port, TLS certificates path).
 
----
-
 Users should now be able to login to the Container Registry using their GitLab
 credentials:
 
@@ -252,8 +238,6 @@ Registry application itself.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `registry` entry and
@@ -272,8 +256,6 @@ If the Container Registry is enabled, then it will be available on all new
 projects. To disable this function and let the owners of a project to enable
 the Container Registry by themselves, follow the steps below.
 
----
-
 **Omnibus GitLab installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` and add the following line:
@@ -284,8 +266,6 @@ the Container Registry by themselves, follow the steps below.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open `/home/git/gitlab/config/gitlab.yml`, find the `default_projects_features`
@@ -321,8 +301,6 @@ This path is accessible to:
 > **Warning** You should confirm that all GitLab, Registry and web server users
 have access to this directory.
 
----
-
 **Omnibus GitLab installations**
 
 The default location where images are stored in Omnibus, is
@@ -336,8 +314,6 @@ The default location where images are stored in Omnibus, is
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 The default location where images are stored in source installations, is
@@ -446,8 +422,6 @@ In the examples below we set the Registry's port to `5001`.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 1. Open the configuration file of your Registry server and edit the
@@ -565,8 +539,6 @@ To configure a notification endpoint in Omnibus:
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **Installations from source**
 
 Configuring the notification endpoint is done in your registry config YML file created
@@ -640,8 +612,6 @@ Start with a value between `25000000` (25MB) and `50000000` (50MB).
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **For installations from source**
 
 1. Edit `config/gitlab.yml`:
@@ -673,8 +643,6 @@ You can add a configuration option for backwards compatibility.
 
 1. Save the file and [reconfigure GitLab][] for the changes to take effect.
 
----
-
 **For installations from source**
 
 1. Edit the YML configuration file you created when you [deployed the registry][registry-deploy]. Add the following snippet:
diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md
index dc49a95e008..5aedb665935 100644
--- a/doc/administration/geo/replication/index.md
+++ b/doc/administration/geo/replication/index.md
@@ -14,14 +14,8 @@ Fetching large repositories can take a long time for teams located far from a si
 
 Geo provides local, read-only instances of your GitLab instances, reducing the time it takes to clone and fetch large repositories and speeding up development.
 
-> **Notes:**
->
-> - Geo is part of [GitLab Premium](https://about.gitlab.com/pricing/#self-managed).
-> - We recommend you use:
->   - At least GitLab Enterprise Edition 10.0 for basic Geo features.
->   - The latest version for a better experience.
-> - Make sure that all nodes run the same GitLab version.
-> - Geo requires PostgreSQL 9.6 and Git 2.9, in addition to GitLab's usual [minimum requirements](../../../install/requirements.md).
+NOTE: **Note:**
+Check the [requirements](#requirements-for-running-geo) carefully before setting up Geo.
 
 For a video introduction to Geo, see [Introduction to GitLab Geo - GitLab Features](https://www.youtube.com/watch?v=-HDLxSjEh6w).
 
@@ -117,6 +111,13 @@ The following are required to run Geo:
   - [Ubuntu](https://www.ubuntu.com) 16.04+
 - PostgreSQL 9.6+ with [FDW](https://www.postgresql.org/docs/9.6/postgres-fdw.html) support and [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication)
 - Git 2.9+
+- All nodes must run the same GitLab version.
+
+Additionally, check GitLab's [minimum requirements](../../../install/requirements.md),
+and we recommend you use:
+
+- At least GitLab Enterprise Edition 10.0 for basic Geo features.
+- The latest version for a better experience.
 
 ### Firewall rules
 
diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md
index 0b945bc6244..b99724d12a2 100644
--- a/doc/administration/high_availability/pgbouncer.md
+++ b/doc/administration/high_availability/pgbouncer.md
@@ -20,84 +20,85 @@ It is recommended to run pgbouncer alongside the `gitlab-rails` service, or on i
 
 1. Edit `/etc/gitlab/gitlab.rb` replacing values noted in the `# START user configuration` section:
 
-    ```ruby
-    # Disable all components except Pgbouncer and Consul agent
-    roles ['pgbouncer_role']
-
-    # Configure Pgbouncer
-    pgbouncer['admin_users'] = %w(pgbouncer gitlab-consul)
-
-    # Configure Consul agent
-    consul['watchers'] = %w(postgresql)
-
-    # START user configuration
-    # Please set the real values as explained in Required Information section
-    # Replace CONSUL_PASSWORD_HASH with with a generated md5 value
-    # Replace PGBOUNCER_PASSWORD_HASH with with a generated md5 value
-    pgbouncer['users'] = {
-      'gitlab-consul': {
-        password: 'CONSUL_PASSWORD_HASH'
-      },
-      'pgbouncer': {
-        password: 'PGBOUNCER_PASSWORD_HASH'
-      }
-    }
-    # Replace placeholders:
-    #
-    # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
-    # with the addresses gathered for CONSUL_SERVER_NODES
-    consul['configuration'] = {
-      retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
-    }
-    #
-    # END user configuration
-    ```
-
-    > `pgbouncer_role` was introduced with GitLab 10.3
-
-1.  Run `gitlab-ctl reconfigure`
+   ```ruby
+   # Disable all components except Pgbouncer and Consul agent
+   roles ['pgbouncer_role']
+
+   # Configure Pgbouncer
+   pgbouncer['admin_users'] = %w(pgbouncer gitlab-consul)
+
+   # Configure Consul agent
+   consul['watchers'] = %w(postgresql)
+
+   # START user configuration
+   # Please set the real values as explained in Required Information section
+   # Replace CONSUL_PASSWORD_HASH with with a generated md5 value
+   # Replace PGBOUNCER_PASSWORD_HASH with with a generated md5 value
+   pgbouncer['users'] = {
+     'gitlab-consul': {
+       password: 'CONSUL_PASSWORD_HASH'
+     },
+     'pgbouncer': {
+       password: 'PGBOUNCER_PASSWORD_HASH'
+     }
+   }
+   # Replace placeholders:
+   #
+   # Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z
+   # with the addresses gathered for CONSUL_SERVER_NODES
+   consul['configuration'] = {
+     retry_join: %w(Y.Y.Y.Y consul1.gitlab.example.com Z.Z.Z.Z)
+   }
+   #
+   # END user configuration
+   ```
+
+   NOTE: **Note:**
+   `pgbouncer_role` was introduced with GitLab 10.3.
+
+1. Run `gitlab-ctl reconfigure`
 
 1. Create a `.pgpass` file so Consul is able to
    reload pgbouncer. Enter the `PGBOUNCER_PASSWORD` twice when asked:
 
-    ```sh
-    gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
-    ```
+   ```sh
+   gitlab-ctl write-pgpass --host 127.0.0.1 --database pgbouncer --user pgbouncer --hostuser gitlab-consul
+   ```
 
 #### PGBouncer Checkpoint
 
 1. Ensure the node is talking to the current master:
 
-    ```sh
-    gitlab-ctl pgb-console # You will be prompted for PGBOUNCER_PASSWORD
-    ```
+   ```sh
+   gitlab-ctl pgb-console # You will be prompted for PGBOUNCER_PASSWORD
+   ```
 
-    If there is an error `psql: ERROR:  Auth failed` after typing in the
-    password, ensure you previously generated the MD5 password hashes with the correct
-    format. The correct format is to concatenate the password and the username:
-    `PASSWORDUSERNAME`. For example, `Sup3rS3cr3tpgbouncer` would be the text
-    needed to generate an MD5 password hash for the `pgbouncer` user.
+   If there is an error `psql: ERROR:  Auth failed` after typing in the
+   password, ensure you previously generated the MD5 password hashes with the correct
+   format. The correct format is to concatenate the password and the username:
+   `PASSWORDUSERNAME`. For example, `Sup3rS3cr3tpgbouncer` would be the text
+   needed to generate an MD5 password hash for the `pgbouncer` user.
 
 1. Once the console prompt is available, run the following queries:
 
-    ```sh
-    show databases ; show clients ;
-    ```
-
-    The output should be similar to the following:
+   ```sh
+   show databases ; show clients ;
+   ```
 
-    ```
-            name         |  host       | port |      database       | force_user | pool_size | reserve_pool | pool_mode | max_connections | current_connections
-    ---------------------+-------------+------+---------------------+------------+-----------+--------------+-----------+-----------------+---------------------
-     gitlabhq_production | MASTER_HOST | 5432 | gitlabhq_production |            |        20 |            0 |           |               0 |                   0
-     pgbouncer           |             | 6432 | pgbouncer           | pgbouncer  |         2 |            0 | statement |               0 |                   0
-    (2 rows)
+   The output should be similar to the following:
 
-     type |   user    |      database       |  state  |   addr         | port  | local_addr | local_port |    connect_time     |    request_time     |    ptr    | link | remote_pid | tls
-    ------+-----------+---------------------+---------+----------------+-------+------------+------------+---------------------+---------------------+-----------+------+------------+-----
-     C    | pgbouncer | pgbouncer           | active  | 127.0.0.1      | 56846 | 127.0.0.1  |       6432 | 2017-08-21 18:09:59 | 2017-08-21 18:10:48 | 0x22b3880 |      |          0 |
-    (2 rows)
-    ```
+   ```
+           name         |  host       | port |      database       | force_user | pool_size | reserve_pool | pool_mode | max_connections | current_connections
+   ---------------------+-------------+------+---------------------+------------+-----------+--------------+-----------+-----------------+---------------------
+    gitlabhq_production | MASTER_HOST | 5432 | gitlabhq_production |            |        20 |            0 |           |               0 |                   0
+    pgbouncer           |             | 6432 | pgbouncer           | pgbouncer  |         2 |            0 | statement |               0 |                   0
+   (2 rows)
+
+    type |   user    |      database       |  state  |   addr         | port  | local_addr | local_port |    connect_time     |    request_time     |    ptr    | link | remote_pid | tls
+   ------+-----------+---------------------+---------+----------------+-------+------------+------------+---------------------+---------------------+-----------+------+------------+-----
+    C    | pgbouncer | pgbouncer           | active  | 127.0.0.1      | 56846 | 127.0.0.1  |       6432 | 2017-08-21 18:09:59 | 2017-08-21 18:10:48 | 0x22b3880 |      |          0 |
+   (2 rows)
+   ```
 
 ### Running Pgbouncer as part of a non-HA GitLab installation
 
diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md
index b2cad6cf926..c77a1a9638f 100644
--- a/doc/administration/pages/source.md
+++ b/doc/administration/pages/source.md
@@ -24,8 +24,6 @@ SNI and exposes pages using HTTP2 by default.
 You are encouraged to read its [README][pages-readme] to fully understand how
 it works.
 
----
-
 In the case of [custom domains](#custom-domains) (but not
 [wildcard domains](#wildcard-domains)), the Pages daemon needs to listen on
 ports `80` and/or `443`. For that reason, there is some flexibility in the way
@@ -92,8 +90,6 @@ since that is needed in all configurations.
 
 - [Wildcard DNS setup](#dns-configuration)
 
----
-
 URL scheme: `http://page.example.io`
 
 This is the minimum setup that you can use Pages with. It is the base for all
@@ -152,13 +148,12 @@ The Pages daemon doesn't listen to the outside world.
 
 ### Wildcard domains with TLS support
 
-> **Requirements:**
-> - [Wildcard DNS setup](#dns-configuration)
-> - Wildcard TLS certificate
->
-> ---
->
-> URL scheme: `https://page.example.io`
+**Requirements:**
+
+- [Wildcard DNS setup](#dns-configuration)
+- Wildcard TLS certificate
+
+URL scheme: `https://page.example.io`
 
 Nginx will proxy all requests to the daemon. Pages daemon doesn't listen to the
 outside world.
@@ -217,13 +212,12 @@ that without TLS certificates.
 
 ### Custom domains
 
-> **Requirements:**
-> - [Wildcard DNS setup](#dns-configuration)
-> - Secondary IP
->
-> ---
->
-> URL scheme: `http://page.example.io` and `http://domain.com`
+**Requirements:**
+
+- [Wildcard DNS setup](#dns-configuration)
+- Secondary IP
+
+URL scheme: `http://page.example.io` and `http://domain.com`
 
 In that case, the pages daemon is running, Nginx still proxies requests to
 the daemon but the daemon is also able to receive requests from the outside
@@ -282,14 +276,13 @@ world. Custom domains are supported, but no TLS.
 
 ### Custom domains with TLS support
 
-> **Requirements:**
-> - [Wildcard DNS setup](#dns-configuration)
-> - Wildcard TLS certificate
-> - Secondary IP
->
-> ---
->
-> URL scheme: `https://page.example.io` and `https://domain.com`
+**Requirements:**
+
+- [Wildcard DNS setup](#dns-configuration)
+- Wildcard TLS certificate
+- Secondary IP
+
+URL scheme: `https://page.example.io` and `https://domain.com`
 
 In that case, the pages daemon is running, Nginx still proxies requests to
 the daemon but the daemon is also able to receive requests from the outside
diff --git a/doc/administration/raketasks/storage.md b/doc/administration/raketasks/storage.md
index 2f83dd17d9f..1198f3414c5 100644
--- a/doc/administration/raketasks/storage.md
+++ b/doc/administration/raketasks/storage.md
@@ -105,8 +105,6 @@ sudo gitlab-rake gitlab:storage:legacy_projects
 sudo -u git -H bundle exec rake gitlab:storage:legacy_projects RAILS_ENV=production
 ```
 
----
-
 To list projects using **Legacy** storage:
 
 **Omnibus Installation**
@@ -138,8 +136,6 @@ sudo gitlab-rake gitlab:storage:hashed_projects
 sudo -u git -H bundle exec rake gitlab:storage:hashed_projects RAILS_ENV=production
 ```
 
----
-
 To list projects using **Hashed** storage:
 
 **Omnibus Installation**
@@ -170,8 +166,6 @@ sudo gitlab-rake gitlab:storage:legacy_attachments
 sudo -u git -H bundle exec rake gitlab:storage:legacy_attachments RAILS_ENV=production
 ```
 
----
-
 To list project attachments using **Legacy** storage:
 
 **Omnibus Installation**
@@ -202,8 +196,6 @@ sudo gitlab-rake gitlab:storage:hashed_attachments
 sudo -u git -H bundle exec rake gitlab:storage:hashed_attachments RAILS_ENV=production
 ```
 
----
-
 To list project attachments using **Hashed** storage:
 
 **Omnibus Installation**
diff --git a/doc/ci/environments.md b/doc/ci/environments.md
index 61559e69182..9e1a62bae71 100644
--- a/doc/ci/environments.md
+++ b/doc/ci/environments.md
@@ -591,15 +591,13 @@ exist, you should see something like:
 
 ### Monitoring environments
 
-> **Notes:**
->
-> - For the monitoring dashboard to appear, you need to:
->   - Enable the [Prometheus integration](../user/project/integrations/prometheus.md).
->   - Configure Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/index.md).
-> - With GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
-
 If you have enabled [Prometheus for monitoring system and response metrics](../user/project/integrations/prometheus.md),
-you can monitor the behavior of your app running in each environment.
+you can monitor the behavior of your app running in each environment. For the monitoring
+dashboard to appear, you need to Configure Prometheus to collect at least one
+[supported metric](../user/project/integrations/prometheus_library/index.md).
+
+NOTE: **Note:**
+Since GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.
 
 Once configured, GitLab will attempt to retrieve [supported performance metrics](../user/project/integrations/prometheus_library/index.md)
 for any environment that has had a successful deployment. If monitoring data was
diff --git a/doc/development/fe_guide/event_tracking.md b/doc/development/fe_guide/event_tracking.md
index 1e6287d8f6d..715d91c6db6 100644
--- a/doc/development/fe_guide/event_tracking.md
+++ b/doc/development/fe_guide/event_tracking.md
@@ -40,10 +40,9 @@ Below is a list of supported `data-track-*` attributes:
 | attribute             | required | description |
 |:----------------------|:---------|:------------|
 | `data-track-event`    | true     | Action the user is taking. Clicks should be `click` and activations should be `activate`, so for example, focusing a form field would be `activate_form_input`, and clicking a button would be `click_button`. |
-| `data-track-label`    | false    | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy) |
-| `data-track-property` | false    | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy)
-| `data-track-value`    | false    | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). If omitted, this will be the elements `value` property or an empty string. For checkboxes, the default value will be the element's checked attribute or `false` when unchecked. 
-
+| `data-track-label`    | false    | The `label` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
+| `data-track-property` | false    | The `property` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). |
+| `data-track-value`    | false    | The `value` as described [in our Feature Instrumentation taxonomy](https://about.gitlab.com/handbook/product/feature-instrumentation/#taxonomy). If omitted, this will be the elements `value` property or an empty string. For checkboxes, the default value will be the element's checked attribute or `false` when unchecked. |
 
 ## Tracking in raw Javascript
 
@@ -69,7 +68,6 @@ document.getElementById('my_button').addEventListener('click', () => {
 })
 ```
 
-
 ## Toggling tracking on or off
 
 Snowplow can be enabled by navigating to:
diff --git a/doc/development/filtering_by_label.md b/doc/development/filtering_by_label.md
index 6e6b71b1787..5e7376db725 100644
--- a/doc/development/filtering_by_label.md
+++ b/doc/development/filtering_by_label.md
@@ -35,7 +35,7 @@ LIMIT 20 OFFSET 0
 In particular, note that:
 
 1. We `GROUP BY issues.id` so that we can ...
-2. Use the `HAVING (COUNT(DISTINCT labels.title) = 2)` condition to ensure that
+1. Use the `HAVING (COUNT(DISTINCT labels.title) = 2)` condition to ensure that
    all matched issues have both labels.
 
 This is more complicated than is ideal. It makes the query construction more
@@ -103,7 +103,7 @@ This has some strong advantages over titles:
 
 1. Unless a label is deleted, or a project is moved, we never need to
    bulk-update the denormalized column.
-2. It uses less storage than the titles.
+1. It uses less storage than the titles.
 
 Unfortunately, our application design makes this hard. If we were able to query
 just by label ID easily, we wouldn't need the `INNER JOIN labels` in the initial
@@ -115,7 +115,7 @@ We do not want users to have to know about the different IDs, which means that
 given this data set:
 
 | Project | ~Plan label ID | ~backend label ID |
-| ---     | ---            | ---               |
+| ------- | -------------- | ----------------- |
 | A       | 11             | 12                |
 | B       | 21             | 22                |
 | C       | 31             | 32                |
diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md
index 882e2230636..d6b944a3e74 100644
--- a/doc/development/testing_guide/end_to_end/index.md
+++ b/doc/development/testing_guide/end_to_end/index.md
@@ -83,7 +83,6 @@ subgraph "gitlab-qa pipeline"
     end
 ```
 
-
 1. Developer triggers a manual action, that can be found in CE / EE merge
    requests. This starts a chain of pipelines in multiple projects.
 
diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md
index 52957d1a1ab..47e58a425fd 100644
--- a/doc/development/testing_guide/end_to_end/page_objects.md
+++ b/doc/development/testing_guide/end_to_end/page_objects.md
@@ -105,7 +105,7 @@ code but **this is deprecated** in favor of the above method for two reasons:
 view 'app/views/my/view.html.haml' do
 
   ### Good ###
- 
+
   # Implicitly require the CSS selector `[data-qa-selector="logout_button"]` to be present in the view
   element :logout_button
 
@@ -152,10 +152,9 @@ Things to note:
 - The name of the element and the qa_selector must match and be snake_cased
 - If the element appears on the page unconditionally, add `required: true` to the element. See
   [Dynamic element validation](dynamic_element_validation.md)
-- You may see `.qa-selector` classes in existing Page Objects.  We should prefer the [`data-qa-selector`](#data-qa-selector-vs-qa-selector) 
+- You may see `.qa-selector` classes in existing Page Objects.  We should prefer the [`data-qa-selector`](#data-qa-selector-vs-qa-selector)
   method of definition over the `.qa-selector` CSS class
 
-
 ### `data-qa-selector` vs `.qa-selector`
 
 > Introduced in GitLab 12.1
diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md
index b4f2025265e..b791cbd428d 100644
--- a/doc/integration/kerberos.md
+++ b/doc/integration/kerberos.md
@@ -67,8 +67,6 @@ For source installations, make sure the `kerberos` gem group
 
 1. [Restart GitLab] for the changes to take effect.
 
----
-
 **Omnibus package installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
@@ -83,8 +81,6 @@ For source installations, make sure the `kerberos` gem group
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
----
-
 GitLab will now offer the `negotiate` authentication method for signing in and
 HTTP Git access, enabling Git clients that support this authentication protocol
 to authenticate with Kerberos tokens.
@@ -172,8 +168,6 @@ keep offering only `basic` authentication.
 
 1. [Restart GitLab] and NGINX for the changes to take effect.
 
----
-
 **For Omnibus package installations**
 
 1. Edit `/etc/gitlab/gitlab.rb`:
@@ -186,8 +180,6 @@ keep offering only `basic` authentication.
 
 1. [Reconfigure GitLab] for the changes to take effect.
 
----
-
 After this change, all Git remote URLs will have to be updated to
 `https://gitlab.example.com:8443/mygroup/myproject.git` in order to use
 Kerberos ticket-based authentication.
@@ -223,8 +215,6 @@ remove the OmniAuth provider named `kerberos` from your `gitlab.yml` /
 
 1. [Restart GitLab] for the changes to take effect.
 
----
-
 **For Omnibus installations**
 
 1. Edit `/etc/gitlab/gitlab.rb` and remove the `{ "name" => "kerberos" }` line
diff --git a/doc/topics/git/partial_clone.md b/doc/topics/git/partial_clone.md
index f2951308ba1..ea4223355d8 100644
--- a/doc/topics/git/partial_clone.md
+++ b/doc/topics/git/partial_clone.md
@@ -99,49 +99,49 @@ enabled on the Git server:
    shared-component-b/
    ```
 
-2. *Create a new Git repository and fetch.* Support for `--filter=sparse:oid`
+1. *Create a new Git repository and fetch.* Support for `--filter=sparse:oid`
    using the clone command is incomplete, so we will emulate the clone command
    by hand, using `git init` and `git fetch`. Follow
    [gitaly#1769](https://gitlab.com/gitlab-org/gitaly/issues/1769) for updates.
 
-    ```bash
-    # Create a new directory for the Git repository
-    mkdir jumbo-repo && cd jumbo-repo
+   ```bash
+   # Create a new directory for the Git repository
+   mkdir jumbo-repo && cd jumbo-repo
 
-    # Initialize a new Git repository
-    git init
+   # Initialize a new Git repository
+   git init
 
-    # Add the remote
-    git remote add origin git@gitlab.com/example/jumbo-repo
+   # Add the remote
+   git remote add origin git@gitlab.com/example/jumbo-repo
 
-    # Enable partial clone support for the remote
-    git config --local extensions.partialClone origin
+   # Enable partial clone support for the remote
+   git config --local extensions.partialClone origin
 
-    # Fetch the filtered set of objects using the filterspec stored on the
-    # server. WARNING: this step is slow!
-    git fetch --filter=sparse:oid=master:shiny-app/.gitfilterspec origin
+   # Fetch the filtered set of objects using the filterspec stored on the
+   # server. WARNING: this step is slow!
+   git fetch --filter=sparse:oid=master:shiny-app/.gitfilterspec origin
 
-    # Optional: observe there are missing objects that we have not fetched
-    git rev-list --all --quiet --objects --missing=print | wc -l
-    ```
+   # Optional: observe there are missing objects that we have not fetched
+   git rev-list --all --quiet --objects --missing=print | wc -l
+   ```
 
-    CAUTION: **IDE and Shell integrations:**
-    Git integrations with `bash`, `zsh`, etc and editors that automatically
-    show Git status information often run `git fetch` which will fetch the
-    entire repository. You many need to disable or reconfigure these
-    integrations.
+   CAUTION: **IDE and Shell integrations:**
+   Git integrations with `bash`, `zsh`, etc and editors that automatically
+   show Git status information often run `git fetch` which will fetch the
+   entire repository. You many need to disable or reconfigure these
+   integrations.
 
-3. **Sparse checkout** must be enabled and configured to prevent objects from
+1. **Sparse checkout** must be enabled and configured to prevent objects from
    other paths being downloaded automatically when checking out branches. Follow
    [gitaly#1765](https://gitlab.com/gitlab-org/gitaly/issues/1765) for updates.
 
-    ```bash
-    # Enable sparse checkout
-    git config --local core.sparsecheckout true
+   ```bash
+   # Enable sparse checkout
+   git config --local core.sparsecheckout true
 
-    # Configure sparse checkout
-    git show master:snazzy-app/.gitfilterspec >> .git/info/sparse-checkout
+   # Configure sparse checkout
+   git show master:snazzy-app/.gitfilterspec >> .git/info/sparse-checkout
 
-    # Checkout master
-    git checkout master
-    ```
+   # Checkout master
+   git checkout master
+   ```
diff --git a/doc/user/project/integrations/jira_cloud_configuration.md b/doc/user/project/integrations/jira_cloud_configuration.md
index 5a5ba2dd168..1d5a4a3d4c7 100644
--- a/doc/user/project/integrations/jira_cloud_configuration.md
+++ b/doc/user/project/integrations/jira_cloud_configuration.md
@@ -9,7 +9,7 @@ below to create one:
    It is important that the user associated with this email address has *write* access
    to projects in Jira.
 
-2. Click **Create API token**.
+1. Click **Create API token**.
 
 ![Jira API token](img/jira_api_token_menu.png)
 
diff --git a/doc/user/project/merge_requests/merge_request_dependencies.md b/doc/user/project/merge_requests/merge_request_dependencies.md
index 45cb56dfb6b..e046b3466c4 100644
--- a/doc/user/project/merge_requests/merge_request_dependencies.md
+++ b/doc/user/project/merge_requests/merge_request_dependencies.md
@@ -23,11 +23,11 @@ merge requests in the same project cannot depend on each other.
 
 ## Use cases
 
-* Ensure changes to a library are merged before changes to a project that
+- Ensure changes to a library are merged before changes to a project that
   imports the library
-* Prevent a documentation-only merge request from being merged before the merge request
+- Prevent a documentation-only merge request from being merged before the merge request
   implementing the feature to be documented
-* Require an merge request updating a permissions matrix to be merged before merging an
+- Require an merge request updating a permissions matrix to be merged before merging an
   merge request from someone who hasn't yet been granted permissions
 
 It is common for a single logical change to span several merge requests, spread
@@ -97,9 +97,9 @@ merge.
 
 ## Limitations
 
-* API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551)
-* Dependencies are not preserved across project export/import: [gitlab-ee#12549](https://gitlab.com/gitlab-org/gitlab-ee/issues/12549)
-* Complex merge order dependencies are not supported: [gitlab-ee#11393](https://gitlab.com/gitlab-org/gitlab-ee/issues/11393)
+- API support: [gitlab-ee#12551](https://gitlab.com/gitlab-org/gitlab-ee/issues/12551)
+- Dependencies are not preserved across project export/import: [gitlab-ee#12549](https://gitlab.com/gitlab-org/gitlab-ee/issues/12549)
+- Complex merge order dependencies are not supported: [gitlab-ee#11393](https://gitlab.com/gitlab-org/gitlab-ee/issues/11393)
 
 The last item merits a little more explanation. Dependencies between merge
 requests can be described as a graph of relationships. The simplest possible
@@ -122,7 +122,6 @@ graph LR;
 Several different merge requests can also directly depend upon the
 same merge request:
 
-
 ```mermaid
 graph LR;
     herfriend/another-lib!1-->myfriend/awesome-lib!10;
diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
index 6a9900d48f9..29f8e3fa0f7 100644
--- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
+++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md
@@ -192,13 +192,13 @@ can use the following setup:
 1. In GitLab, verify your domain.
 1. In Cloudflare, create a DNS `CNAME` record pointing `www` to `domain.com`.
 1. In Cloudflare, add a Page Rule pointing `www.domain.com` to `domain.com`:
-    - Navigate to your domain's dashboard and click **Page Rules**
-      on the top nav.
-    - Click **Create Page Rule**.
-    - Enter the domain `www.domain.com` and click **+ Add a Setting**.
-    - From the dropdown menu, choose **Forwarding URL**, then select the
-      status code **301 - Permanent Redirect**.
-    - Enter the destination URL `https://domain.com`.
+   - Navigate to your domain's dashboard and click **Page Rules**
+     on the top nav.
+   - Click **Create Page Rule**.
+   - Enter the domain `www.domain.com` and click **+ Add a Setting**.
+   - From the dropdown menu, choose **Forwarding URL**, then select the
+     status code **301 - Permanent Redirect**.
+   - Enter the destination URL `https://domain.com`.
 
 ## Adding an SSL/TLS certificate to Pages
 
@@ -263,7 +263,6 @@ To enable this setting:
 1. Navigate to your project's **Settings > Pages**.
 1. Tick the checkbox **Force HTTPS (requires valid certificates)**.
 
-
 <!-- ## Troubleshooting
 
 Include any troubleshooting steps that you can foresee. If you know beforehand what issues
diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md
index 437899dce1e..6758adf2b43 100644
--- a/doc/user/project/quick_actions.md
+++ b/doc/user/project/quick_actions.md
@@ -77,8 +77,8 @@ you manually enter a parameter, it must be enclosed in double quotation marks
 (`"`), unless it contains only:
 
 1. ASCII letters.
-2. Numerals.
-3. Underscore, hyphen, question mark, dot, and ampersand.
+1. Numerals.
+1. Underscore, hyphen, question mark, dot, and ampersand.
 
 Parameters are also case-sensitive. Autocomplete handles this, and the insertion
 of quotation marks, automatically.