Add latest changes from gitlab-org/gitlab@master

8 files changed, 160 insertions, 77 deletions

diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md
index a340f8b705d..c90d2e1aa5e 100644
--- a/doc/ci/variables/predefined_variables.md
+++ b/doc/ci/variables/predefined_variables.md
@@ -51,11 +51,11 @@ future GitLab releases.**
 | `CI_ENVIRONMENT_NAME`                         | 8.15   | all    | The name of the environment for this job. Only present if [`environment:name`](../yaml/README.md#environmentname) is set.                                                                                                                                                                                                                                  |
 | `CI_ENVIRONMENT_SLUG`                         | 8.15   | all    | A simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, etc. Only present if [`environment:name`](../yaml/README.md#environmentname) is set.                                                                                                                                                                 |
 | `CI_ENVIRONMENT_URL`                          | 9.3    | all    | The URL of the environment for this job. Only present if [`environment:url`](../yaml/README.md#environmenturl) is set.                                                                                                                                                                                                                                     |
-| `CI_EXTERNAL_PULL_REQUEST_IID`                | 12.3   | all    | Pull Request ID from GitHub if the [pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open.                                                                                                         |
-| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME` | 12.3   | all    | The source branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open.                                                                                          |
-| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA`  | 12.3   | all    | The HEAD SHA of the source branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open.                                                                               |
-| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME` | 12.3   | all    | The target branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open.                                                                                          |
-| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA`  | 12.3   | all    | The HEAD SHA of the target branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` is used and the pull request is open.                                                                               |
+| `CI_EXTERNAL_PULL_REQUEST_IID`                | 12.3   | all    | Pull Request ID from GitHub if the [pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open.                                                                                                         |
+| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_NAME` | 12.3   | all    | The source branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open.                                                                                          |
+| `CI_EXTERNAL_PULL_REQUEST_SOURCE_BRANCH_SHA`  | 12.3   | all    | The HEAD SHA of the source branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open.                                                                               |
+| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_NAME` | 12.3   | all    | The target branch name of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open.                                                                                          |
+| `CI_EXTERNAL_PULL_REQUEST_TARGET_BRANCH_SHA`  | 12.3   | all    | The HEAD SHA of the target branch of the pull request if [the pipelines are for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). Available only if `only: [external_pull_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the pull request is open.                                                                               |
 | `CI_JOB_ID`                                   | 9.0    | all    | The unique id of the current job that GitLab CI uses internally                                                                                                                                                                                                                                                                                            |
 | `CI_JOB_IMAGE`                                | 12.9   | 12.9   | The name of the image running the CI job                                                                                                                                                                                                                                                                                                                   |
 | `CI_JOB_MANUAL`                               | 8.12   | all    | The flag to indicate that job was manually started                                                                                                                                                                                                                                                                                                         |
@@ -63,25 +63,25 @@ future GitLab releases.**
 | `CI_JOB_STAGE`                                | 9.0    | 0.5    | The name of the stage as defined in `.gitlab-ci.yml`                                                                                                                                                                                                                                                                                                       |
 | `CI_JOB_TOKEN`                                | 9.0    | 1.2    | Token used for authenticating with the [GitLab Container Registry][registry] and downloading [dependent repositories][dependent-repositories]                                                                                                                                                                                                              |
 | `CI_JOB_URL`                                  | 11.1   | 0.5    | Job details URL                                                                                                                                                                                                                                                                                                                                            |
-| `CI_MERGE_REQUEST_ASSIGNEES`                  | 11.9   | all    | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                              |
+| `CI_MERGE_REQUEST_ASSIGNEES`                  | 11.9   | all    | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                              |
 | `CI_MERGE_REQUEST_CHANGED_PAGE_PATHS`         | 12.9   | all    | Comma-separated list of paths of changed pages in a deployed [Review App](../review_apps/index.md) for a [Merge Request](../merge_request_pipelines/index.md). A [Route Map](../review_apps/index.md#route-maps) must be configured.                                                                                 |
 | `CI_MERGE_REQUEST_CHANGED_PAGE_URLS`          | 12.9   | all    | Comma-separated list of URLs of changed pages in a deployed [Review App](../review_apps/index.md) for a [Merge Request](../merge_request_pipelines/index.md). A [Route Map](../review_apps/index.md#route-maps) must be configured.                                                                                  |
-| `CI_MERGE_REQUEST_ID`                         | 11.6   | all    | The ID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                                           |
-| `CI_MERGE_REQUEST_IID`                        | 11.6   | all    | The IID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                                          |
-| `CI_MERGE_REQUEST_LABELS`                     | 11.9   | all    | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                      |
-| `CI_MERGE_REQUEST_MILESTONE`                  | 11.9   | all    | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                              |
-| `CI_MERGE_REQUEST_PROJECT_ID`                 | 11.6   | all    | The ID of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                            |
-| `CI_MERGE_REQUEST_PROJECT_PATH`               | 11.6   | all    | The path of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `namespace/awesome-project`). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                       |
-| `CI_MERGE_REQUEST_PROJECT_URL`                | 11.6   | all    | The URL of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                              |
-| `CI_MERGE_REQUEST_REF_PATH`                   | 11.6   | all    | The ref path of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                |
-| `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`         | 11.6   | all    | The source branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                           |
-| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`          | 11.9   | all    | The HEAD SHA of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)**   |
-| `CI_MERGE_REQUEST_SOURCE_PROJECT_ID`          | 11.6   | all    | The ID of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                     |
-| `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`        | 11.6   | all    | The path of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                   |
-| `CI_MERGE_REQUEST_SOURCE_PROJECT_URL`         | 11.6   | all    | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                    |
-| `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`         | 11.6   | all    | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                           |
-| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA`          | 11.9   | all    | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)**   |
-| `CI_MERGE_REQUEST_TITLE`                      | 11.9   | all    | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created.                                                                                                                                                        |
+| `CI_MERGE_REQUEST_ID`                         | 11.6   | all    | The ID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                                           |
+| `CI_MERGE_REQUEST_IID`                        | 11.6   | all    | The IID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                                          |
+| `CI_MERGE_REQUEST_LABELS`                     | 11.9   | all    | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                      |
+| `CI_MERGE_REQUEST_MILESTONE`                  | 11.9   | all    | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                              |
+| `CI_MERGE_REQUEST_PROJECT_ID`                 | 11.6   | all    | The ID of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                            |
+| `CI_MERGE_REQUEST_PROJECT_PATH`               | 11.6   | all    | The path of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `namespace/awesome-project`). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                       |
+| `CI_MERGE_REQUEST_PROJECT_URL`                | 11.6   | all    | The URL of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                              |
+| `CI_MERGE_REQUEST_REF_PATH`                   | 11.6   | all    | The ref path of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                |
+| `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME`         | 11.6   | all    | The source branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                           |
+| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA`          | 11.9   | all    | The HEAD SHA of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)**   |
+| `CI_MERGE_REQUEST_SOURCE_PROJECT_ID`          | 11.6   | all    | The ID of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                     |
+| `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH`        | 11.6   | all    | The path of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                   |
+| `CI_MERGE_REQUEST_SOURCE_PROJECT_URL`         | 11.6   | all    | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                    |
+| `CI_MERGE_REQUEST_TARGET_BRANCH_NAME`         | 11.6   | all    | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                           |
+| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA`          | 11.9   | all    | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or [`rules`](../yaml/README.md#rules) syntax is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)**   |
+| `CI_MERGE_REQUEST_TITLE`                      | 11.9   | all    | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` or  [`rules`](../yaml/README.md#rules) syntax is used and the merge request is created.                                                                                                                                                        |
 | `CI_MERGE_REQUEST_EVENT_TYPE`                 | 12.3   | all    | The event type of the merge request, if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Can be `detached`, `merged_result` or `merge_train`. |
 | `CI_NODE_INDEX`                               | 11.5   | all    | Index of the job in the job set. If the job is not parallelized, this variable is not set.                                                                                                                                                                                                                                                                 |
 | `CI_NODE_TOTAL`                               | 11.5   | all    | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`.                                                                                                                                                                                                                                    |
diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md
index bd5ea6ac506..8537c63a8b7 100644
--- a/doc/development/api_styleguide.md
+++ b/doc/development/api_styleguide.md
@@ -11,6 +11,12 @@ to access them as we do in Rails views), local variables are fine.
 
 Always use an [Entity] to present the endpoint's payload.
 
+## Documentation
+
+API endpoints must come with [documentation](documentation/styleguide.md#api), unless it is internal or behind a feature flag.
+The docs should be in the same merge request, or, if strictly necessary,
+in a follow-up with the same milestone as the original merge request.  
+
 ## Methods and parameters description
 
 Every method must be described using the [Grape DSL](https://github.com/ruby-grape/grape#describing-methods)
diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md
index 8e97427e061..e1056eb2002 100644
--- a/doc/user/application_security/index.md
+++ b/doc/user/application_security/index.md
@@ -7,9 +7,11 @@ type: reference, howto
 GitLab can check your application for security vulnerabilities that may lead to unauthorized access,
 data leaks, denial of services, and more. GitLab reports vulnerabilities in the merge request so you
 can fix them before merging. The [Security Dashboard](security_dashboard/index.md) provides a
-high-level view of vulnerabilities detected in your projects, pipeline, and groups. With the
-information provided, you can immediately begin risk analysis and remediation.
+high-level view of vulnerabilities detected in your projects, pipeline, and groups. The [Threat Monitoring](threat_monitoring/index.md)
+page provides runtime security metrics for application environments. With the information provided,
+you can immediately begin risk analysis and remediation.
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
 For an overview of application security with GitLab, see
 [Security Deep Dive](https://www.youtube.com/watch?v=k4vEJnGYy84).
 
diff --git a/doc/user/application_security/offline_deployments/index.md b/doc/user/application_security/offline_deployments/index.md
index f72b632ff82..6fc16684d79 100644
--- a/doc/user/application_security/offline_deployments/index.md
+++ b/doc/user/application_security/offline_deployments/index.md
@@ -13,7 +13,7 @@ connected to the internet, in what is sometimes known as an offline,
 limited connectivity, Local Area Network (LAN), Intranet, or "air-gap"
 environment.
 
-In this situation, the GitLab instance can be one, or more, servers and services running in a network that can talk to one another, but have zero, or perhaps very restricted access to the internet. Assume anything within the GitLab instance and supporting infrastrusture (private maven repository for example) can be accessed via local network connection. Assume any files from the internet must come in via physical media (USB drive, hard drive).
+In this situation, the GitLab instance can be one, or more, servers and services running in a network that can talk to one another, but have zero, or perhaps very restricted access to the internet. Assume anything within the GitLab instance and supporting infrastructure (private Maven repository for example) can be accessed via local network connection. Assume any files from the internet must come in via physical media (USB drive, hard drive).
 
 GitLab scanners generally will connect to the internet to download the
 latest sets of signatures, rules, and patches. A few extra steps are necessary
diff --git a/doc/user/application_security/threat_monitoring/index.md b/doc/user/application_security/threat_monitoring/index.md
new file mode 100644
index 00000000000..07427af7c7d
--- /dev/null
+++ b/doc/user/application_security/threat_monitoring/index.md
@@ -0,0 +1,40 @@
+---
+type: reference, howto
+---
+
+# Threat Monitoring **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14707) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9.
+
+The **Threat Monitoring** page provides metrics for the GitLab
+application runtime security features. You can access these metrics by
+navigating to your project's **Security & Compliance > Threat Monitoring** page.
+
+GitLab supports statistics for the following security features:
+
+- [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity)
+
+## Web Application Firewall
+
+The Web Application Firewall section provides metrics for the NGINX
+Ingress controller and ModSecurity firewall. This section has the
+following prerequisites:
+
+- Project has to have at least one [environment](../../../ci/environments.md).
+- [Web Application Firewall](../../clusters/applications.md#web-application-firewall-modsecurity) has to be enabled.
+- [Elastic Stack](../../clusters/applications.md#web-application-firewall-modsecurity) has to be installed.
+
+If you are using custom Helm values for the Elastic Stack you have to
+configure Filebeat similarly to the [vendored values](https://gitlab.com/gitlab-org/gitlab/-/blob/f610a080b1ccc106270f588a50cb3c07c08bdd5a/vendor/elastic_stack/values.yaml).
+
+The **Web Application Firewall** section displays the following information
+about your Ingress traffic:
+
+- The total amount of requests to your application
+- The proportion of traffic that is considered anomalous according to
+  the configured rules
+- The request breakdown graph for the selected time interval
+
+If a significant percentage of traffic is anomalous, you should
+investigate it for potential threats by
+[examining the application logs](../../clusters/applications.md#web-application-firewall-modsecurity).
diff --git a/doc/user/img/markdown_toc_preview_v12_9.png b/doc/user/img/markdown_toc_preview_v12_9.png
new file mode 100644
index 00000000000..dd832d2788c
--- /dev/null
+++ b/doc/user/img/markdown_toc_preview_v12_9.png
diff --git a/doc/user/markdown.md b/doc/user/markdown.md
index 29163f98fb4..882ded57684 100644
--- a/doc/user/markdown.md
+++ b/doc/user/markdown.md
@@ -45,10 +45,10 @@ in October 2018.
 
 You may have older issues, merge requests, or Markdown documents in your
 repository that were written using some of the nuances of GitLab's RedCarpet version
-of Markdown. Since CommonMark uses a slightly stricter syntax, these documents
-may now display a little differently since we've transitioned to CommonMark.
+of Markdown. Since CommonMark uses slightly stricter syntax, these documents
+might now appear a little differently since we have transitioned to CommonMark.
 
-It is usually quite easy to fix. For example, numbered lists with nested lists may
+It's usually quite easy to fix. For example, numbered lists with nested lists may
 render incorrectly:
 
 ```markdown
@@ -119,7 +119,7 @@ changing how standard Markdown is used:
 
 > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#colors).
 
-It is possible to have color written in HEX, RGB or HSL format rendered with a color
+It's possible to have color written in HEX, RGB, or HSL format rendered with a color
 indicator.
 
 Supported formats (named colors are not supported):
@@ -154,14 +154,14 @@ Color written inside backticks will be followed by a color "chip":
 
 ### Diagrams and flowcharts
 
-It is possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](http://plantuml.com).
+It's possible to generate diagrams and flowcharts from text in GitLab using [Mermaid](https://mermaidjs.github.io/) or [PlantUML](http://plantuml.com).
 
 #### Mermaid
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/15107) in
 GitLab 10.3.
 
-Visit the [official page](https://mermaidjs.github.io/) for more details. If you are new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams.
+Visit the [official page](https://mermaidjs.github.io/) for more details. If you're new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams.
 
 In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block:
 
@@ -236,7 +236,7 @@ Sometimes you want to :monkey: around a bit and add some :star2: to your :speech
 
 You can use it to point out a :bug: or warn about :speak_no_evil: patches. And if someone improves your really :snail: code, send them some :birthday:. People will :heart: you for that.
 
-If you are new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
+If you're new to this, don't be :fearful:. You can easily join the emoji :family:. All you need to do is to look up one of the supported codes.
 
 Consult the [Emoji Cheat Sheet](https://www.emojicopy.com) for a list of all supported emoji codes. :thumbsup:
 ```
@@ -247,7 +247,7 @@ Sometimes you want to <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/ma
 
 You can use it to point out a <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/bug.png" width="20px" height="20px" style="display:inline;margin:0"> or warn about <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/speak_no_evil.png" width="20px" height="20px" style="display:inline;margin:0"> patches. And if someone improves your really <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/snail.png" width="20px" height="20px" style="display:inline;margin:0"> code, send them some <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/birthday.png" width="20px" height="20px" style="display:inline;margin:0">. People will <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/heart.png" width="20px" height="20px" style="display:inline;margin:0"> you for that.
 
-If you are new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes.
+If you're new to this, don't be <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/fearful.png" width="20px" height="20px" style="display:inline;margin:0">. You can easily join the emoji <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/family.png" width="20px" height="20px" style="display:inline;margin:0">. All you need to do is to look up one of the supported codes.
 
 Consult the [Emoji Cheat Sheet](https://www.webfx.com/tools/emoji-cheat-sheet/) for a list of all supported emoji codes. <img src="https://gitlab.com/gitlab-org/gitlab-foss/raw/master/app/assets/images/emoji/thumbsup.png" width="20px" height="20px" style="display:inline;margin:0">
 
@@ -345,7 +345,7 @@ The wrapping tags can be either curly braces or square brackets:
 
 ---
 
-However the wrapping tags cannot be mixed:
+However, the wrapping tags can't be mixed:
 
 ```markdown
 - {+ addition +]
@@ -354,11 +354,24 @@ However the wrapping tags cannot be mixed:
 - [- deletion -}
 ```
 
+If your diff includes words in `` `code` `` font, make sure to escape each bactick `` ` `` with a
+backslash `\`, otherwise the diff highlight won't render correctly:
+
+```markdown
+- {+ Just regular text +}
+- {+ Text with `backticks` inside +}
+- {+ Text with escaped \`backticks\` inside +}
+```
+
+- {+ Just regular text +}
+- {+ Text with `backticks` inside +}
+- {+ Text with escaped \`backticks\` inside +}
+
 ### Math
 
 > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#math).
 
-It is possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX).
+It's possible to have math written with LaTeX syntax rendered using [KaTeX](https://github.com/KaTeX/KaTeX).
 
 Math written between dollar signs `$` will be rendered inline with the text. Math written
 inside a [code block](#code-spans-and-blocks) with the language declared as `math`, will be rendered
@@ -462,22 +475,35 @@ unordered or ordered lists:
    1. [ ] Sub-task 1
    1. [x] Sub-task 2
 
-### Table of Contents
+### Table of contents
 
-A table of contents can be added to a Markdown file, issue or merge request
-description, or a wiki page, by adding the tag `[[_TOC_]]` on its own line.
-It will be replaced with an unordered list that links to the various
-headers.
+You can add a table of contents to a Markdown file, wiki page, or issue/merge request
+description, by adding the tag `[[_TOC_]]` on its own line.
+It will appear as an unordered list that links to the various headers.
 
 ```markdown
+This is an intro sentence to my Wiki page.
+
 [[_TOC_]]
+
+## My first heading
+
+First section content.
+
+## My second heading
+
+Second section content.
 ```
 
+![Preview of an auto-generated TOC in a Wiki](img/markdown_toc_preview_v12_9.png)
+
+---
+
 ### Wiki-specific Markdown
 
 The following examples show how links inside wikis behave.
 
-#### Wiki - Direct page link
+#### Wiki - direct page link
 
 A link which just includes the slug for a page will point to that page,
 _at the base level of the wiki_.
@@ -488,7 +514,7 @@ This snippet would link to a `documentation` page at the root of your wiki:
 [Link to Documentation](documentation)
 ```
 
-#### Wiki - Direct file link
+#### Wiki - direct file link
 
 Links with a file extension point to that file, _relative to the current page_.
 
@@ -499,10 +525,10 @@ it would link to `<your_wiki>/documentation/file.md`:
 [Link to File](file.md)
 ```
 
-#### Wiki - Hierarchical link
+#### Wiki - hierarchical link
 
 A link can be constructed relative to the current wiki page using `./<page>`,
-`../<page>`, etc.
+`../<page>`, and so on.
 
 If this snippet was placed on a page at `<your_wiki>/documentation/main`,
 it would link to `<your_wiki>/documentation/related`:
@@ -532,7 +558,7 @@ it would link to `<your_wiki>/documentation/main.md`:
 [Link to Related Page](../main.md)
 ```
 
-#### Wiki - Root link
+#### Wiki - root link
 
 A link starting with a `/` is relative to the wiki root.
 
@@ -560,7 +586,7 @@ If a functionality is extended, the new option will be listed as a sub-section.
 
 ### Blockquotes
 
-Blockquotes are an easy way to highlight information, such as a side-note. It is generated
+Blockquotes are an easy way to highlight information, such as a side-note. It's generated
 by starting the lines of the blockquote with `>`:
 
 ```markdown
@@ -667,8 +693,8 @@ Tildes are OK too.
 GitLab uses the [Rouge Ruby library](http://rouge.jneen.net/) for more colorful syntax
 highlighting in code blocks. For a list of supported languages visit the
 [Rouge project wiki](https://github.com/rouge-ruby/rouge/wiki/List-of-supported-languages-and-lexers).
-Syntax highlighting is only supported in code blocks, it is not possible to highlight
-code when it is inline.
+Syntax highlighting is only supported in code blocks, so it's not possible to highlight
+code when it's inline.
 
 Blocks of code are fenced by lines with three back-ticks (```` ``` ````) or three tildes (`~~~`), and have
 the language identified at the end of the first fence:
@@ -756,7 +782,7 @@ NOTE: **Note:** Strikethrough is not part of the core Markdown standard, but is
 
 > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#multiple-underscores-in-words).
 
-It is not usually useful to italicize just _part_ of a word, especially when you're
+It's not usually useful to italicize just _part_ of a word, especially when you're
 dealing with code and names that often appear with multiple underscores. As a result,
 GFM extends the standard Markdown standard by ignoring multiple underlines in words,
 to allow better rendering of Markdown documents discussing code:
@@ -793,7 +819,8 @@ do*this*and*do*that*and*another thing
 
 Footnotes add a link to a note that will be rendered at the end of a Markdown file.
 
-To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with the note content.
+To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with
+the note content.
 
 Regardless of the tag names, the relative order of the reference tags determines the rendered numbering.
 
@@ -804,20 +831,23 @@ A footnote reference tag looks like this:[^1]
 
 Reference tags can use letters and other characters.[^footnote-note]
 
-[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`)
-in your footnote tag name until an
-[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved.
-```
+Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
+[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
 
-A footnote reference tag looks like this:[^1]
+[^this-name-has-w]: This won't be rendered, because the name contains "w".
 
-[^1]: This is the contents of a footnote.
+[^this-name-has_]: This won be rendered, because the name contains an underscore.
+
+```
 
 Reference tags can use letters and other characters.[^footnote-note]
 
-[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`)
-in your footnote tag name until an
-[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved.
+Avoid using lowercase `w` or an underscore (`_`) in footnote tag names until
+[this bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. [^this-name-has-w] [^this-name-has_]
+
+[^this-name-has-w]: This won't be rendered, because the name contains "w".
+
+[^this-name-has_]: This won't be rendered, because the name contains an underscore.
 
 ### Headers
 
@@ -849,7 +879,7 @@ the header to use it somewhere else.
 The IDs are generated from the content of the header according to the following rules:
 
 1. All text is converted to lowercase.
-1. All non-word text (e.g., punctuation, HTML) is removed.
+1. All non-word text (such as punctuation or HTML) is removed.
 1. All spaces are converted to hyphens.
 1. Two or more hyphens in a row are converted to one.
 1. If a header with the same ID has already been generated, a unique
@@ -875,8 +905,8 @@ Would generate the following link IDs:
 1. `this-header-has-spaces-in-it-2`
 1. `this-header-has-3-5-in-it-and-parentheses`
 
-Note that the Emoji processing happens before the header IDs are generated, so the
-Emoji is converted to an image which is then removed from the ID.
+Note that the emoji processing happens before the header IDs are generated, so the
+emoji is converted to an image which is then removed from the ID.
 
 ### Horizontal Rule
 
@@ -966,7 +996,7 @@ Here's a sample audio clip:
 
 > To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#inline-html).
 
-You can also use raw HTML in your Markdown, and it'll usually work pretty well.
+You can also use raw HTML in your Markdown, and it will usually work pretty well.
 
 See the documentation for HTML::Pipeline's [SanitizationFilter](https://www.rubydoc.info/gems/html-pipeline/1.11.0/HTML/Pipeline/SanitizationFilter#WHITELIST-constant)
 class for the list of allowed HTML tags and attributes. In addition to the default
@@ -992,7 +1022,7 @@ class for the list of allowed HTML tags and attributes. In addition to the defau
 
 ---
 
-It is still possible to use Markdown inside HTML tags, but only if the lines containing Markdown
+It's still possible to use Markdown inside HTML tags, but only if the lines containing Markdown
 are separated into their own lines:
 
 ```html
@@ -1023,7 +1053,7 @@ are separated into their own lines:
   </dd>
 </dl>
 
-#### Details and Summary
+#### Details and summary
 
 > To see the Markdown rendered within HTML in the second example, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/user/markdown.md#details-and-summary).
 
@@ -1034,7 +1064,7 @@ tags. This is especially useful for collapsing long logs so they take up less sc
 ```html
 <p>
 <details>
-<summary>Click me to collapse/fold.</summary>
+<summary>Click this to collapse/fold.</summary>
 
 These details <em>will</em> remain <strong>hidden</strong> until expanded.
 
@@ -1046,7 +1076,7 @@ These details <em>will</em> remain <strong>hidden</strong> until expanded.
 
 <p>
 <details>
-<summary>Click me to collapse/fold.</summary>
+<summary>Click this to collapse/fold.</summary>
 
 These details <em>will</em> remain <strong>hidden</strong> until expanded.
 
@@ -1062,7 +1092,7 @@ after the `</summary>` tag and before the `</details>` tag, as shown in the exam
 
 ````html
 <details>
-<summary>Click me to collapse/fold.</summary>
+<summary>Click this to collapse/fold.</summary>
 
 These details _will_ remain **hidden** until expanded.
 
@@ -1076,7 +1106,7 @@ PASTE LOGS HERE
 <!-- Note: The example below uses HTML to force correct rendering on docs.gitlab.com, Markdown will be fine in GitLab -->
 
 <details>
-<summary>Click me to collapse/fold.</summary>
+<summary>Click this to collapse/fold.</summary>
 
 These details <em>will</em> remain <b>hidden</b> until expanded.
 
@@ -1084,10 +1114,10 @@ These details <em>will</em> remain <b>hidden</b> until expanded.
 
 </details>
 
-### Line Breaks
+### Line breaks
 
 A line break will be inserted (a new paragraph will start) if the previous text is
-ended with two newlines, i.e. you hit <kbd>Enter</kbd> twice in a row. If you only
+ended with two newlines, like when you hit <kbd>Enter</kbd> twice in a row. If you only
 use one newline (hit <kbd>Enter</kbd> once), the next sentence will be part of the
 same paragraph. This is useful if you want to keep long lines from wrapping, and keep
 them easily editable:
@@ -1116,8 +1146,8 @@ in the *same paragraph*.
 
 GFM adheres to the Markdown specification in how [paragraphs and line breaks are handled](https://spec.commonmark.org/current/).
 
-A paragraph is simply one or more consecutive lines of text, separated by one or
-more blank lines (i.e. two newlines at the end of the first paragraph), as [explained above](#line-breaks).
+A paragraph is one or more consecutive lines of text, separated by one or
+more blank lines (two newlines at the end of the first paragraph), as [explained above](#line-breaks).
 
 If you need more control over line-breaks or soft returns, you can add a single line-break
 by ending a line with a backslash, or two or more spaces. Two newlines in a row will create a new
@@ -1340,7 +1370,7 @@ Example:
 
 ### Superscripts / Subscripts
 
-CommonMark and GFM currently do not support the superscript syntax ( `x^2` ) that
+Currently, CommonMark and GFM don't support the superscript syntax ( `x^2` ) that
 Redcarpet does. You can use the standard HTML syntax for superscripts and subscripts:
 
 ```html
@@ -1353,7 +1383,7 @@ while the equation for the theory of relativity is E = mc<sup>2</sup>.
 
 ### Tables
 
-Tables aren't part of the core Markdown spec, but they are part of GFM.
+Tables are not part of the core Markdown spec, but they are part of GFM.
 
 1. The first line contains the headers, separated by "pipes" (`|`).
 1. The second line separates the headers from the cells, and must contain three or more dashes.
@@ -1401,8 +1431,8 @@ to the sides of the "dash" lines in the second row. This will affect every cell
 
 [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/27205) in GitLab 12.7.
 
-If you're working in spreadsheet software (e.g. Microsoft Excel, Google
-Sheets, Apple Numbers), you can copy from a spreadsheet, and GitLab will
+If you're working in spreadsheet software (for example, Microsoft Excel, Google
+Sheets, or Apple Numbers), you can copy from a spreadsheet, and GitLab will
 paste it as a Markdown table. For example, suppose you have the
 following spreadsheet:
 
diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md
index 6fda2514849..3255e3a5477 100644
--- a/doc/user/project/wiki/index.md
+++ b/doc/user/project/wiki/index.md
@@ -93,6 +93,11 @@ To edit a page, simply click on the **Edit** button. From there on, you can
 change its content. When done, click **Save changes** for the changes to take
 effect.
 
+### Adding a table of contents
+
+To generate a table of contents from the headings in a Wiki page, use the `[[_TOC_]]` tag.
+For an example, see [Table of contents](../../markdown.md#table-of-contents).
+
 ## Deleting a wiki page
 
 NOTE: **Note:**