Update documentation for compliance with CommonMark

doc/administration/custom_hooks.md

 # Custom Git Hooks
 
 > **Note:** Custom Git hooks must be configured on the filesystem of the GitLab
-server. Only GitLab server administrators will be able to complete these tasks.
-Please explore [webhooks] and [CI] as an option if you do not
-have filesystem access. For a user configurable Git hook interface, see
-[Push Rules](https://docs.gitlab.com/ee/push_rules/push_rules.html),
-available in GitLab Enterprise Edition.
-
+> server. Only GitLab server administrators will be able to complete these tasks.
+> Please explore [webhooks] and [CI] as an option if you do not
+> have filesystem access. For a user configurable Git hook interface, see
+> [Push Rules](https://docs.gitlab.com/ee/push_rules/push_rules.html),
+> available in GitLab Enterprise Edition.
 >
-**Note:** Custom Git hooks won't be replicated to secondary nodes if you use [GitLab Geo][gitlab-geo]
+> **Note:** Custom Git hooks won't be replicated to secondary nodes if you use [GitLab Geo][gitlab-geo]
 
 Git natively supports hooks that are executed on different actions.
 Examples of server-side git hooks include pre-receive, post-receive, and update.

doc/administration/geo/disaster_recovery/bring_primary_back.md

@@ -25,16 +25,16 @@ To bring the former primary up to date:
     sudo gitlab-ctl start
     ```
 
-    >**Note 1:** If you [disabled primary permanently][disaster-recovery-disable-primary],
-    you need to undo those steps now. For Debian/Ubuntu you just need to run
-    `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
-    the GitLab instance from scratch and setup it as a secondary node by
-    following [Setup instructions][setup-geo].  In this case you don't need to follow the next step.
-
-    >**Note 2:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domains-dns-record)
-    for this node during disaster recovery procedure you may need to [block
-    all the writes to this node](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/planned-failover.md#block-primary-traffic)
-    during this procedure.
+    > **Note 1:** If you [disabled primary permanently][disaster-recovery-disable-primary],
+    > you need to undo those steps now. For Debian/Ubuntu you just need to run
+    > `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install
+    > the GitLab instance from scratch and setup it as a secondary node by
+    > following [Setup instructions][setup-geo].  In this case you don't need to follow the next step.
+    >
+    > **Note 2:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domains-dns-record)
+    > for this node during disaster recovery procedure you may need to [block
+    > all the writes to this node](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/planned-failover.md#block-primary-traffic)
+    > during this procedure.
 
 1. [Setup database replication][database-replication]. Note that in this
    case, primary refers to the current primary, and secondary refers to the

doc/administration/geo/replication/high_availability.md

@@ -151,7 +151,6 @@ be specified.
     gitlab_rails['redis_host'] = '10.1.2.1'
     gitlab_rails['redis_password'] = 'Redis password'
 
-
     ##
     ## Enable the geo secondary role and configure the
     ## geo tracking database

doc/administration/geo/replication/index.md

 # Geo (Geo Replication) **[PREMIUM ONLY]**
 
 > **Notes:**
-- Geo is part of [GitLab Premium][ee]
-- Introduced in GitLab Enterprise Edition 8.9
-  We recommend you use it with at least GitLab Enterprise Edition 10.0 for
-  basic Geo features, or latest version for a better experience
-- You should 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]
-- Using Geo in combination with High Availability (HA) is considered **Generally Available** (GA) in GitLab Enterprise Edition 10.4
-
->**Note:**
-Geo changes significantly from release to release. Upgrades **are**
-supported and [documented](#updating-the-geo-nodes), but you should ensure that
-you're following the right version of the documentation for your installation!
-The best way to do this is to follow the documentation from the `/help` endpoint
-on your **primary** node, but you can also navigate to [this page on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/README.md)
-and choose the appropriate release from the `tags` dropdown, e.g., `v10.0.0-ee`.
+> - Geo is part of [GitLab Premium][ee]
+> - Introduced in GitLab Enterprise Edition 8.9
+>   We recommend you use it with at least GitLab Enterprise Edition 10.0 for
+>   basic Geo features, or latest version for a better experience
+> - You should 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]
+> - Using Geo in combination with High Availability (HA) is considered **Generally Available** (GA) in GitLab Enterprise Edition 10.4
+>
+> **Note:**
+> Geo changes significantly from release to release. Upgrades **are**
+> supported and [documented](#updating-the-geo-nodes), but you should ensure that
+> you're following the right version of the documentation for your installation!
+> The best way to do this is to follow the documentation from the `/help` endpoint
+> on your **primary** node, but you can also navigate to [this page on GitLab.com](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/README.md)
+> and choose the appropriate release from the `tags` dropdown, e.g., `v10.0.0-ee`.
 
 Geo allows you to replicate your GitLab instance to other geographical
 locations as a read-only fully operational version.

doc/administration/geo/replication/updating_the_geo_nodes.md

@@ -49,7 +49,8 @@ authentication method.
     # Every node that runs Unicorn or Sidekiq needs to have the database
     # password specified as below. If you have a high-availability setup, this
     # must be present in all application nodes.
-    gitlab_rails['db_password'] = 'mypassword' ```
+    gitlab_rails['db_password'] = 'mypassword'
+    ```
 
     Still in the configuration file, locate and remove the `trust_auth_cidr_address`:
 

doc/administration/high_availability/database.md

@@ -6,13 +6,12 @@ PostgreSQL. This is the database that will be installed if you use the
 Omnibus package to manage your database.
 
 > Important notes:
-- This document will focus only on configuration supported with [GitLab Premium](https://about.gitlab.com/pricing/), using the Omnibus GitLab package.
-- If you are a Community Edition or Starter user, consider using a cloud hosted solution.
-- This document will not cover installations from source.
-
+> - This document will focus only on configuration supported with [GitLab Premium](https://about.gitlab.com/pricing/), using the Omnibus GitLab package.
+> - If you are a Community Edition or Starter user, consider using a cloud hosted solution.
+> - This document will not cover installations from source.
 >
-- If HA setup is not what you were looking for,  see the [database configuration document](http://docs.gitlab.com/omnibus/settings/database.html)
-for the Omnibus GitLab packages.
+> - If HA setup is not what you were looking for,  see the [database configuration document](http://docs.gitlab.com/omnibus/settings/database.html)
+>   for the Omnibus GitLab packages.
 
 ## Configure your own database server
 
@@ -31,12 +30,10 @@ If you use a cloud-managed service, or provide your own PostgreSQL:
 
 ## Configure using Omnibus for High Availability
 
+> Please read this document fully before attempting to configure PostgreSQL HA
+> for GitLab.
 >
-Please read this document fully before attempting to configure PostgreSQL HA
-for GitLab.
-
->
-This configuration is GA in EE 10.2.
+> This configuration is GA in EE 10.2.
 
 The recommended configuration for a PostgreSQL HA requires:
 
@@ -94,12 +91,12 @@ Similarly, PostgreSQL access is controlled based on the network source.
 This is why you will need:
 
 > IP address of each nodes network interface
-- This can be set to `0.0.0.0` to listen on all interfaces. It cannot
-  be set to the loopack address `127.0.0.1`
-
+> - This can be set to `0.0.0.0` to listen on all interfaces. It cannot
+>   be set to the loopack address `127.0.0.1`
+>
 > Network Address
-- This can be in subnet (i.e. `192.168.0.0/255.255.255.0`) or CIDR (i.e.
-  `192.168.0.0/24`) form.
+> - This can be in subnet (i.e. `192.168.0.0/255.255.255.0`) or CIDR (i.e.
+>   `192.168.0.0/24`) form.
 
 #### User information
 
@@ -115,10 +112,12 @@ When using default setup, minimum configuration requires:
 - `CONSUL_USERNAME`. Defaults to `gitlab-consul`
 - `CONSUL_DATABASE_PASSWORD`. Password for the database user.
 - `CONSUL_PASSWORD_HASH`. This is a hash generated out of consul username/password pair.
-Can be generated with:
+   Can be generated with:
+
     ```sh
     sudo gitlab-ctl pg-password-md5 CONSUL_USERNAME
     ```
+
 - `CONSUL_SERVER_NODES`.  The IP addresses or DNS records of the Consul server nodes.
 
 Few notes on the service itself:
@@ -141,7 +140,7 @@ This is used to prevent replication from using up all of the
 available database connections.
 
 > Note:
-- In this document we are assuming 3 database nodes, which makes this configuration:
+> - In this document we are assuming 3 database nodes, which makes this configuration:
 
 ```
 postgresql['max_wal_senders'] = 4
@@ -157,7 +156,8 @@ We will need the following password information for the application's database u
 - `POSTGRESQL_USERNAME`. Defaults to `gitlab`
 - `POSTGRESQL_USER_PASSWORD`. The password for the database user
 - `POSTGRESQL_PASSWORD_HASH`. This is a hash generated out of the username/password pair.
-Can be generated with:
+  Can be generated with:
+
     ```sh
     sudo gitlab-ctl pg-password-md5 POSTGRESQL_USERNAME
     ```
@@ -169,10 +169,12 @@ When using default setup, minimum configuration requires:
 - `PGBOUNCER_USERNAME`. Defaults to `pgbouncer`
 - `PGBOUNCER_PASSWORD`. This is a password for pgbouncer service.
 - `PGBOUNCER_PASSWORD_HASH`. This is a hash generated out of pgbouncer username/password pair.
-Can be generated with:
+  Can be generated with:
+
     ```sh
     sudo gitlab-ctl pg-password-md5 PGBOUNCER_USERNAME
     ```
+
 - `PGBOUNCER_NODE`, is the IP address or a FQDN of the node running Pgbouncer.
 
 Few notes on the service itself:
@@ -321,11 +323,11 @@ check the [Troubleshooting section](#troubleshooting) before proceeding.
 1. [Reconfigure GitLab] for the changes to take effect.
 
 > Please note:
-- If you want your database to listen on a specific interface, change the config:
-`postgresql['listen_address'] = '0.0.0.0'`
-- If your Pgbouncer service runs under a different user account,
-you also need to specify: `postgresql['pgbouncer_user'] = PGBOUNCER_USERNAME` in
-your configuration
+> - If you want your database to listen on a specific interface, change the config:
+>   `postgresql['listen_address'] = '0.0.0.0'`
+> - If your Pgbouncer service runs under a different user account,
+>   you also need to specify: `postgresql['pgbouncer_user'] = PGBOUNCER_USERNAME` in
+>   your configuration
 
 #### Database nodes post-configuration
 
@@ -374,6 +376,7 @@ Select one node as a primary node.
     ```sh
     gitlab-ctl repmgr standby setup MASTER_NODE_NAME
     ```
+
     Do note that this will remove the existing data on the node. The command
     has a wait time.
 

doc/administration/high_availability/gitlab.md

@@ -91,7 +91,7 @@ for each GitLab application server in your environment.
     certificates are not present, Nginx will fail to start. See
     [Nginx documentation](http://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
     for more information.
-    
+    >
     > **Note:** It is best to set the `uid` and `gid`s prior to the initial reconfigure of GitLab. Omnibus will not recursively `chown` directories if set after the initial reconfigure.
 
 ## First GitLab application server

doc/administration/high_availability/pgbouncer.md

@@ -22,6 +22,7 @@ See our [HA documentation for PostgreSQL](database.md) for information on runnin
 1. Generate SQL_USER_PASSWORD_HASH with the command `gitlab-ctl pg-password-md5 gitlab`. We'll also need to enter the plaintext SQL_USER_PASSWORD later
 
 1. On your database node, ensure the following is set in your `/etc/gitlab/gitlab.rb`
+
     ```ruby
     postgresql['pgbouncer_user_password'] = 'PGBOUNCER_USER_PASSWORD_HASH'
     postgresql['sql_user_password'] = 'SQL_USER_PASSWORD_HASH'

doc/administration/maven_packages.md

 # GitLab private Maven repository administration
 
 > **Notes:**
-- [Introduced][ee-5811] in GitLab 11.3.
-- This document is about the admin guide. Learn how to use GitLab Maven 
-  repository from [user documentation](../user/project/maven_packages.md).
+> - [Introduced][ee-5811] in GitLab 11.3.
+> - This document is about the admin guide. Learn how to use GitLab Maven 
+>   repository from [user documentation](../user/project/maven_packages.md).
 
 When enabled, every project in GitLab will have its own space to store Maven packages.
 

doc/ci/chatops/README.md

 # GitLab ChatOps **[ULTIMATE]**
-> **Notes:**
 
+> **Notes:**
+>
 > * [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/4466) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6.
-
+>
 > * ChatOps is currently in alpha, with some important features missing like access control.
 
 GitLab ChatOps provides a method to interact with CI/CD jobs through chat services like Slack. Many organizations' discussion, collaboration, and troubleshooting is taking place in chat services these days, and having a method to run CI/CD jobs with output posted back to the channel can significantly augment a team's workflow.

doc/integration/elasticsearch.md

 # Elasticsearch integration **[STARTER ONLY]**
 
->
-[Introduced][ee-109] in GitLab [Starter][ee] 8.4. Support
-for [Amazon Elasticsearch][aws-elastic] was [introduced][ee-1305] in GitLab
-[Starter][ee] 9.0.
+> [Introduced][ee-109] in GitLab [Starter][ee] 8.4. Support
+> for [Amazon Elasticsearch][aws-elastic] was [introduced][ee-1305] in GitLab
+> [Starter][ee] 9.0.
 
 This document describes how to set up Elasticsearch with GitLab. Once enabled,
 you'll have the benefit of fast search response times and the advantage of two

doc/integration/jira_development_panel.md

@@ -93,11 +93,11 @@ from the left navigation menu. Click `Link GitHub account` to start creating a n
     for all the projects in the GitLab group you specified in the previous step. These are refreshed
     every 60 minutes.
 
-    >**Note:**
-    In the future, we plan on implementating real-time integration. If you need
-    to refresh the data manually, you can do this from the `Applications -> DVCS
-    accounts` screen where you initially set up the integration:
-
+    > **Note:**
+    > In the future, we plan on implementating real-time integration. If you need
+    > to refresh the data manually, you can do this from the `Applications -> DVCS
+    > accounts` screen where you initially set up the integration:
+    >
     > ![Refresh GitLab information in JIRA](img/jira_dev_panel_manual_refresh.png)
 
 To connect additional GitLab projects from other GitLab top-level groups (or personal namespaces), repeat the above

doc/user/admin_area/settings/external_authorization.md

 # External authorization control **[PREMIUM]**
 
->
-[Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4216) in
-[GitLab Premium](https://about.gitlab.com/pricing) 10.6.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4216) in
+> [GitLab Premium](https://about.gitlab.com/pricing) 10.6.
 
 In highly controlled environments, it may be necessary for access policy to be
 controlled by an external service that permits access based on project

doc/user/project/clusters/index.md

@@ -83,14 +83,14 @@ To add an existing Kubernetes cluster to your project:
     - **Kubernetes cluster name** (required) - The name you wish to give the cluster.
     - **Environment scope** (required)- The
       [associated environment](#setting-the-environment-scope) to this cluster.
-    * **API URL** (required) -
+    - **API URL** (required) -
       It's the URL that GitLab uses to access the Kubernetes API. Kubernetes
       exposes several APIs, we want the "base" URL that is common to all of them,
       e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`.
-    * **CA certificate** (optional) -
+    - **CA certificate** (optional) -
       If the API is using a self-signed TLS certificate, you'll also need to include
       the `ca.crt` contents here.
-    * **Token** -
+    - **Token** -
       GitLab authenticates against Kubernetes using service tokens, which are
       scoped to a particular `namespace`. If you don't have a service token yet,
       you can follow the
@@ -104,10 +104,11 @@ To add an existing Kubernetes cluster to your project:
        - Each project should have a unique namespace.
        - The project namespace is not necessarily the namespace of the secret, if
          you're using a secret with broader permissions, like the secret from `default`.
-      * You should **not** use `default` as the project namespace.
-      * If you or someone created a secret specifically for the project, usually
+       - You should **not** use `default` as the project namespace.
+       - If you or someone created a secret specifically for the project, usually
          with limited permissions, the secret's namespace and project namespace may
          be the same.
+
 1.  Finally, click the **Create Kubernetes cluster** button.
 
 After a couple of minutes, your cluster will be ready to go. You can now proceed

doc/user/project/description_templates.md

@@ -57,13 +57,12 @@ changes you made after picking the template and return it to its initial status.
 
 ## Setting a default template for issues and merge requests  **[STARTER]**
 
->
-**Notes:**
-- This feature was introduced before [description templates](#overview) and is
-  available in [GitLab Starter][products]. It can be enabled
-  in the project's settings.
-- Templates for issues were [introduced][ee-28] in GitLab EE 8.1.
-- Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9.
+> **Notes:**
+> - This feature was introduced before [description templates](#overview) and is
+>   available in [GitLab Starter][products]. It can be enabled
+>   in the project's settings.
+> - Templates for issues were [introduced][ee-28] in GitLab EE 8.1.
+> - Templates for merge requests were [introduced][ee-7478ece] in GitLab EE 6.9.
 
 The visibility of issues and/or merge requests should be set to either "Everyone
 with access" or "Only team members" in your project's **Settings** otherwise the

doc/user/project/file_lock.md

 # File Locking **[PREMIUM]**
 
->**Notes:**
-- [Introduced][ee-440] in [GitLab Premium][ee] 8.9.
-- This feature needs to have a license with the "File Lock" option enabled. If
-  you are using Premium but you don't see the "Lock" button,
-  ask your GitLab administrator.
+> **Notes:**
+> - [Introduced][ee-440] in [GitLab Premium][ee] 8.9.
+> - This feature needs to have a license with the "File Lock" option enabled. If
+>   you are using Premium but you don't see the "Lock" button,
+>   ask your GitLab administrator.
 
 File Locking helps you avoid merge conflicts and better manage your binary files.
 Lock any file or directory, make your changes, and then unlock it so another

doc/user/project/merge_requests/index.md

@@ -289,7 +289,7 @@ Each security vulnerability in the report is actionable. Clicking on an entry,
 a detailed information will pop up with two different possible options:
 
 - **Dismiss vulnerability** - Dismissing a vulnerability will place a
-  ~~strikethrough~~ styling on it.
+  <s>strikethrough</s> styling on it.
 - **Create issue** - The new issue will have the title and description
   pre-populated with the information of the vulnerability report.
 

doc/user/project/merge_requests/merge_request_approvals.md

@@ -75,17 +75,16 @@ the following is possible:
 
 - **They are not an eligible approver**: They cannot do anything with respect
   to approving this merge request.
+
 - **They have not approved this merge request**:
+
   - If the required number of approvals has _not_ been yet met, they can approve
     it by clicking the displayed **Approve** button.
       ![Approve](img/approve.png)
-
   - If the required number of approvals has already been met, they can still
     approve it by clicking the displayed **Add approval** button.
       ![Add approval](img/approve_additionally.png)
 
-    ---
-
 - **They have already approved this merge request**: They can remove their approval.
 
     ![Remove approval](img/remove_approval.png)

doc/user/project/milestones/burndown_charts.md

 # Burndown Charts **[STARTER]**
 
->**Notes:**
-- [Introduced][ee-1540] in [GitLab Starter 9.1][ee-9.1] for project milestones.
-- [Introduced][ee-5354] in [GitLab Premium 10.8][ee-10.8] for group milestones.
-- [Added][ee-6495] to [GitLab Starter 11.2][ee-11.2] for group milestones. 
-- Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at`
-  value, so the burndown chart considers them as closed on the milestone
-  `start_date`. In that case, a warning will be displayed.
+> **Notes:**
+> - [Introduced][ee-1540] in [GitLab Starter 9.1][ee-9.1] for project milestones.
+> - [Introduced][ee-5354] in [GitLab Premium 10.8][ee-10.8] for group milestones.
+> - [Added][ee-6495] to [GitLab Starter 11.2][ee-11.2] for group milestones. 
+> - Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at`
+>   value, so the burndown chart considers them as closed on the milestone
+>  `start_date`. In that case, a warning will be displayed.
 
 ## Overview
 
@@ -51,9 +51,8 @@ Find your project's **Burndown Chart** under **Project > Issues > Milestones**,
 and select a milestone from your current ones, while for group's, access the **Groups** dashboard,
 select a group, and go through **Issues > Milestones** on the sidebar.
 
->
-  **Note:** You're able to [promote project][promote-milestone] to group milestones and still
-  see the **Burndown Chart** for them, respecting license limitations.
+> **Note:** You're able to [promote project][promote-milestone] to group milestones and still
+> see the **Burndown Chart** for them, respecting license limitations.
 
 The chart indicates the project's progress throughout that milestone (for issues assigned to it).
 

doc/user/search/advanced_global_search.md

 # Advanced Global Search **[STARTER]**
 
->
-- [Introduced][ee-109] in GitLab [Starter][ee] 8.4.
-- This is the user documentation. To install and configure Elasticsearch,
-  visit the [admin docs](../../integration/elasticsearch.md).
+> - [Introduced][ee-109] in GitLab [Starter][ee] 8.4.
+> - This is the user documentation. To install and configure Elasticsearch,
+>   visit the [admin docs](../../integration/elasticsearch.md).
 
 Leverage Elasticsearch for faster, more advanced code search across your entire
 GitLab instance.

doc/user/search/advanced_search_syntax.md

 # Advanced Syntax Search **[STARTER]**
 
->**Notes:**
-- Introduced in [GitLab Enterprise Starter][ee] 9.2
-- This is the user documentation. To install and configure Elasticsearch,
-  visit the [admin docs](../../integration/elasticsearch.md).
+> **Notes:**
+> - Introduced in [GitLab Enterprise Starter][ee] 9.2
+> - This is the user documentation. To install and configure Elasticsearch,
+>   visit the [admin docs](../../integration/elasticsearch.md).
 
 Use advanced queries for more targeted search results.
 

doc/workflow/git_annex.md

@@ -86,9 +86,8 @@ one is located in `config.yml` of gitlab-shell.
 
 ## Using GitLab git-annex
 
->
-**Note:**
-Your Git remotes must be using the SSH protocol, not HTTP(S).
+> **Note:**
+> Your Git remotes must be using the SSH protocol, not HTTP(S).
 
 Here is an example workflow of uploading a very large file and then checking it
 into your Git repository:

doc/workflow/lfs/migrate_from_git_annex_to_git_lfs.md

@@ -152,6 +152,7 @@ if the server also has Git Annex 6 installed. Read more in the
     indirect  ok
     ok
     ```
+
 ---
 
 At this point, you have two options. Either add, commit and push the files