16 files changed, 58 insertions, 43 deletions

diff --git a/doc/.linting/vale/styles/gitlab/InternalLinkExtension.yml b/doc/.linting/vale/styles/gitlab/InternalLinkExtension.yml
new file mode 100644
index 00000000000..de5dee2325a
--- /dev/null
+++ b/doc/.linting/vale/styles/gitlab/InternalLinkExtension.yml
@@ -0,0 +1,11 @@
+---
+# Checks that internal links have .md extenstion and not .html extension.
+#
+# For a list of all options, see https://errata-ai.github.io/vale/styles/
+extends: existence
+message: Link %s must use the .md file extension.
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation
+level: error
+scope: raw
+raw:
+  - '\[.+\]\((https?:){0}[\w\/\.]+(\.html).*\)'
diff --git a/doc/api/audit_events.md b/doc/api/audit_events.md
index 944d99d8eab..7754f431110 100644
--- a/doc/api/audit_events.md
+++ b/doc/api/audit_events.md
@@ -4,7 +4,7 @@
 
 The Audit Events API allows you to retrieve [instance audit events](../administration/audit_events.md#instance-events-premium-only).
 
-To retrieve audit events using the API, you must [authenticate yourself](README.html#authentication) as an Administrator.
+To retrieve audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator.
 
 ### Retrieve all instance audit events
 
@@ -126,7 +126,7 @@ Example response:
 
 The Group Audit Events API allows you to retrieve [group audit events](../administration/audit_events.md#group-events-starter).
 
-To retrieve group audit events using the API, you must [authenticate yourself](README.html#authentication) as an Administrator or an owner of the group.
+To retrieve group audit events using the API, you must [authenticate yourself](README.md#authentication) as an Administrator or an owner of the group.
 
 ### Retrieve all group audit events
 
diff --git a/doc/api/markdown.md b/doc/api/markdown.md
index bacd9d805bf..3b4b6323022 100644
--- a/doc/api/markdown.md
+++ b/doc/api/markdown.md
@@ -14,7 +14,7 @@ POST /api/v4/markdown
 | --------- | ------- | ------------- | ------------------------------------------ |
 | `text`    | string  | yes           | The Markdown text to render                |
 | `gfm`     | boolean | no (optional) | Render text using GitLab Flavored Markdown. Default is `false` |
-| `project` | string  | no (optional) | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](README.html#authentication) is required if a project is not public.  |
+| `project` | string  | no (optional) | Use `project` as a context when creating references using GitLab Flavored Markdown. [Authentication](README.md#authentication) is required if a project is not public.  |
 
 ```shell
 curl --header Content-Type:application/json --data '{"text":"Hello world! :tada:", "gfm":true, "project":"group_example/project_example"}' https://gitlab.example.com/api/v4/markdown
diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md
index f22d315da00..845a1187a94 100644
--- a/doc/api/repository_files.md
+++ b/doc/api/repository_files.md
@@ -169,7 +169,7 @@ Like [Get file from repository](repository_files.md#get-file-from-repository) yo
 
 ## Create new file in repository
 
-This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions).
+This allows you to create a single file. For creating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
 
 ```plaintext
 POST /projects/:id/repository/files/:file_path
@@ -204,7 +204,7 @@ Parameters:
 
 ## Update existing file in repository
 
-This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions).
+This allows you to update a single file. For updating multiple files with a single request see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
 
 ```plaintext
 PUT /projects/:id/repository/files/:file_path
@@ -250,7 +250,7 @@ Currently GitLab Shell has a boolean return code, preventing GitLab from specify
 
 ## Delete existing file in repository
 
-This allows you to delete a single file. For deleting multiple files with a single request, see the [commits API](commits.html#create-a-commit-with-multiple-files-and-actions).
+This allows you to delete a single file. For deleting multiple files with a single request, see the [commits API](commits.md#create-a-commit-with-multiple-files-and-actions).
 
 ```plaintext
 DELETE /projects/:id/repository/files/:file_path
diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md
index d9522444ef0..cf872b0ee1d 100644
--- a/doc/ci/pipelines.md
+++ b/doc/ci/pipelines.md
@@ -224,8 +224,8 @@ Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.
 
 In particular:
 
-- Jobs are the [basic configuration](yaml/README.html#introduction) component.
-- Stages are defined using the [`stages`](yaml/README.html#stages) keyword.
+- Jobs are the [basic configuration](yaml/README.md#introduction) component.
+- Stages are defined using the [`stages`](yaml/README.md#stages) keyword.
 
 For all available configuration options, see the [GitLab CI/CD Pipeline Configuration Reference](yaml/README.md).
 
diff --git a/doc/development/database_review.md b/doc/development/database_review.md
index 5edaaf4512c..32f67e14fe3 100644
--- a/doc/development/database_review.md
+++ b/doc/development/database_review.md
@@ -85,7 +85,7 @@ the following preparations into account.
 - Make migrations reversible by using the `change` method or include a `down` method when using `up`.
   - Include either a rollback procedure or describe how to rollback changes.
 - Add the output of the migration(s) to the MR description.
-- Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.html) for more details.
+- Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.md) for more details.
 
 #### Preparation when adding or modifying queries
 
diff --git a/doc/development/documentation/structure.md b/doc/development/documentation/structure.md
index 1bb3dd3521b..e7a43f769b3 100644
--- a/doc/development/documentation/structure.md
+++ b/doc/development/documentation/structure.md
@@ -99,7 +99,7 @@ Larger instruction sets may have subsections covering specific phases of the pro
 Where appropriate, provide examples of code or configuration files to better clarify intended usage.
 
 - Write a step-by-step guide, with no gaps between the steps.
-- Include example code or configurations as part of the relevant step. Use appropriate markdown to [wrap code blocks with syntax highlighting](../../user/markdown.html#colored-code-and-syntax-highlighting).
+- Include example code or configurations as part of the relevant step. Use appropriate markdown to [wrap code blocks with syntax highlighting](../../user/markdown.md#colored-code-and-syntax-highlighting).
 - Start with an h2 (`##`), break complex steps into small steps using
 subheadings h3 > h4 > h5 > h6. _Never skip a hierarchy level, such
 as h2 > h4_, as it will break the TOC and may affect the breadcrumbs.
diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md
index 67b1f7eb1f1..9381082af85 100644
--- a/doc/development/documentation/styleguide.md
+++ b/doc/development/documentation/styleguide.md
@@ -642,19 +642,15 @@ do not use this option until further notice.
 
   Don't:
 
-  ```md
-  [merge requests](../../merge_requests/)
-  [issues](../../issues/tags.html)
-  [issue tags](../../issues/tags.html#stages)
-  ```
+  - `../../merge_requests/`
+  - `../../issues/tags.html`
+  - `../../issues/tags.html#stages`
 
   Do:
 
-  ```md
-  [merge requests](../../merge_requests/index.md)
-  [issues](../../issues/tags.md)
-  [issue tags](../../issues/tags.md#stages)
-  ```
+  - `../../merge_requests/index.md`
+  - `../../issues/tags.md`
+  - `../../issues/tags.md#stages`
 
 - Using the Markdown extension is necessary for the [`/help`](index.md#gitlab-help)
   section of GitLab.
diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md
index 619c6fdb7a1..5ba63cc07fa 100644
--- a/doc/development/testing_guide/frontend_testing.md
+++ b/doc/development/testing_guide/frontend_testing.md
@@ -782,7 +782,7 @@ All tests in `spec/javascripts/` will eventually be migrated to `spec/frontend/`
 
 Before May 2018, `features/` also contained feature tests run by Spinach. These tests were removed from the codebase in May 2018 ([#23036](https://gitlab.com/gitlab-org/gitlab-foss/issues/23036)).
 
-See also [Notes on testing Vue components](../fe_guide/vue.html#testing-vue-components).
+See also [Notes on testing Vue components](../fe_guide/vue.md#testing-vue-components).
 
 ## Test helpers
 
diff --git a/doc/development/testing_guide/review_apps.md b/doc/development/testing_guide/review_apps.md
index 0f7780907f6..1ba8bf10179 100644
--- a/doc/development/testing_guide/review_apps.md
+++ b/doc/development/testing_guide/review_apps.md
@@ -101,10 +101,10 @@ subgraph "CNG-mirror pipeline"
 ### Auto-stopping of Review Apps
 
 Review Apps are automatically stopped 2 days after the last deployment thanks to
-the [Environment auto-stop](../../ci/environments.html#environments-auto-stop) feature.
+the [Environment auto-stop](../../ci/environments.md#environments-auto-stop) feature.
 
 If you need your Review App to stay up for a longer time, you can
-[pin its environment](../../ci/environments.html#auto-stop-example) or retry the
+[pin its environment](../../ci/environments.md#auto-stop-example) or retry the
 `review-deploy` job to update the "latest deployed at" time.
 
 The `review-cleanup` job that automatically runs in scheduled
diff --git a/doc/ssh/README.md b/doc/ssh/README.md
index ef24f234f42..fa4a5bdccdf 100644
--- a/doc/ssh/README.md
+++ b/doc/ssh/README.md
@@ -334,20 +334,23 @@ git remote set-url origin git@<user_1.gitlab.com>:gitlab-org/gitlab.git
 
 ## Deploy keys
 
-### Per-repository deploy keys
-
 Deploy keys allow read-only or read-write (if enabled) access to one or
-multiple projects with a single SSH key pair.
+multiple repositories with a single SSH key pair.
 
-This is really useful for cloning repositories to your Continuous
+This is useful for cloning repositories to your Continuous
 Integration (CI) server. By using deploy keys, you don't have to set up a
 dummy user account.
 
-Project maintainers and owners can add a deploy key. To add one:
+If you don't have a key pair, you might want to use a
+[deploy token](../user/project/deploy_tokens/index.md#deploy-tokens) instead.
+
+### Per-repository deploy keys
+
+Project maintainers and owners can add a deploy key for a repository.
 
-1. Go to the settings page:
-   - On GitLab 12.8 and earlier, navigate to the project's **Settings > Repository**.
-   - On GitLab 12.9 and later, navigate to the project's **Settings > CI / CD**.
+1. Navigate to the project's **Settings** page, then:
+   - On GitLab 12.8 and earlier, click **Repository**.
+   - On GitLab 12.9 and later, click **CI / CD**.
 1. Expand the **Deploy Keys** section.
 1. Specify a title for the new deploy key and paste a public SSH key.
 
@@ -356,7 +359,7 @@ read-write (if enabled) access to the project.
 
 You can't add the same deploy key twice using the form.
 If you want to add the same key to another project, please enable it in the
-list that says 'Deploy keys from projects available to you'. All the deploy
+list that says **Deploy keys from projects available to you**. All the deploy
 keys of all the projects you have access to are available. This project
 access can happen through being a direct member of the project, or through
 a group.
@@ -366,10 +369,10 @@ project.
 
 ### Global shared deploy keys
 
-Global Shared Deploy keys allow read-only or read-write (if enabled) access to
-be configured on any repository in the entire GitLab installation.
+Global Shared Deploy keys allow read-only or read-write access to
+any repository in the entire GitLab installation.
 
-This is really useful for integrating repositories to secured, shared Continuous
+This is useful for integrating repositories to secured, shared Continuous
 Integration (CI) services or other shared services.
 GitLab administrators can set up the Global Shared Deploy key in GitLab and
 add the private key to any shared systems. Individual repositories opt into
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index a6f7b2ba7af..43c23bfe34d 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -245,7 +245,7 @@ group.
 1. Introduced in GitLab 12.2.
 1. Default project creation role can be changed at:
    - The [instance level](admin_area/settings/visibility_and_access_controls.md#default-project-creation-protection).
-   - The [group level](group/index.html#default-project-creation-level).
+   - The [group level](group/index.md#default-project-creation-level).
 
 ### Subgroup permissions
 
diff --git a/doc/user/project/deploy_tokens/index.md b/doc/user/project/deploy_tokens/index.md
index 75dd242cb81..03b580c320a 100644
--- a/doc/user/project/deploy_tokens/index.md
+++ b/doc/user/project/deploy_tokens/index.md
@@ -3,10 +3,11 @@
 > - [Introduced][ce-17894] in GitLab 10.7.
 > - [Moved](https://gitlab.com/gitlab-org/gitlab/issues/199370) from **Settings > Repository** in GitLab 12.9.
 
-Deploy tokens allow you to download (through `git clone`) or read the container registry images of a project without having a user and a password.
+Deploy tokens allow you to download (`git clone`) or read the container registry images of a project without having a user and a password.
 
-Please note that deploy tokens expire on the date you define,
-at midnight UTC, and that they can be only managed by [maintainers](../../permissions.md).
+Deploy tokens can be managed by [maintainers only](../../permissions.md).
+
+If you have a key pair, you might want to use [deploy keys](../../../ssh/README.md#deploy-keys) instead.
 
 ## Creating a Deploy Token
 
@@ -24,6 +25,10 @@ You can create as many deploy tokens as you like from the settings of your proje
 
 ![Personal access tokens page](img/deploy_tokens.png)
 
+## Deploy token expiration
+
+Deploy tokens expire on the date you define, at midnight UTC.
+
 ## Revoking a deploy token
 
 At any time, you can revoke any deploy token by just clicking the
diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md
index 3c2ca7e6e59..51e687252a1 100644
--- a/doc/user/project/integrations/prometheus.md
+++ b/doc/user/project/integrations/prometheus.md
@@ -76,7 +76,7 @@ The Prometheus server will [automatically detect and monitor](https://prometheus
 - `prometheus.io/port` to define the port of the metrics endpoint.
 - `prometheus.io/path` to define the path of the metrics endpoint. Defaults to `/metrics`.
 
-CPU and Memory consumption is monitored, but requires [naming conventions](prometheus_library/kubernetes.html#specifying-the-environment) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/), this is handled automatically.
+CPU and Memory consumption is monitored, but requires [naming conventions](prometheus_library/kubernetes.md#specifying-the-environment) in order to determine the environment. If you are using [Auto DevOps](../../../topics/autodevops/), this is handled automatically.
 
 The [NGINX Ingress](../clusters/index.md#installing-applications) that is deployed by GitLab to clusters, is automatically annotated for monitoring providing key response metrics: latency, throughput, and error rates.
 
@@ -834,7 +834,7 @@ If the "No data found" screen continues to appear, it could be due to:
 - No successful deployments have occurred to this environment.
 - Prometheus does not have performance data for this environment, or the metrics
   are not labeled correctly. To test this, connect to the Prometheus server and
-  [run a query](prometheus_library/kubernetes.html#metrics-supported), replacing `$CI_ENVIRONMENT_SLUG`
+  [run a query](prometheus_library/kubernetes.md#metrics-supported), replacing `$CI_ENVIRONMENT_SLUG`
   with the name of your environment.
 - You may need to re-add the GitLab predefined common metrics. This can be done by running the [import common metrics rake task](../../../administration/raketasks/maintenance.md#import-common-metrics).
 
diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md
index 7e600338678..a4b7f0e5fb4 100644
--- a/doc/user/project/merge_requests/code_quality.md
+++ b/doc/user/project/merge_requests/code_quality.md
@@ -269,7 +269,7 @@ Once the Code Quality job has completed:
   The Code Quality widget in the merge request compares the reports from the base and head of the branch,
   then lists any violations that will be resolved or created when the branch is merged.
 - The full JSON report is available as a
-  [downloadable artifact](../../../ci/pipelines/job_artifacts.html#downloading-artifacts)
+  [downloadable artifact](../../../ci/pipelines/job_artifacts.md#downloading-artifacts)
   for the `code_quality` job.
 
 If multiple jobs in a pipeline generate a code quality artifact, only the artifact from
diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md
index 9ca9b3c0358..f67f0896de4 100644
--- a/doc/user/project/pipelines/settings.md
+++ b/doc/user/project/pipelines/settings.md
@@ -285,7 +285,7 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?st
 
 ## Environment Variables
 
-[Environment variables](../../../ci/variables/README.html#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.
+[Environment variables](../../../ci/variables/README.md#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.
 
 ## Deploy Keys