Add Vale checks to project

- Adds error-only configution.
- Makes check part of CI pipeline.
- Fixes errors in content.

.vale.ini

@@ -0,0 +1,9 @@
+# Vale configuration file.
+#
+# For more information, see https://errata-ai.gitbook.io/vale/getting-started/configuration.
+
+StylesPath = doc/.vale
+MinAlertLevel = suggestion
+
+[*.md]
+BasedOnStyles = gitlab

doc/.vale/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).*\)'

doc/.vale/gitlab/RelativeLinks.yml

@@ -0,0 +1,11 @@
+---
+# Checks for the presence of absolute hyperlinks that should be relative.
+#
+# For a list of all options, see https://errata-ai.github.io/vale/styles/
+extends: existence
+message: Link %s must be relative.
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#links-to-internal-documentation
+level: error
+scope: raw
+raw:
+  - '\[.+\]\(https?:\/\/docs\.gitlab\.com\/omnibus.*\)'

doc/.vale/gitlab/SentenceSpacing.yml

@@ -0,0 +1,15 @@
+---
+# Checks for the following in common content scenarios:
+#
+# - No spaces.
+# - More than one space.
+#
+# For a list of all options, see https://errata-ai.github.io/vale/styles/
+extends: existence
+message: '"%s" must contain one and only one space.'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#punctuation
+level: error
+nonword: true
+tokens:
+  - '[a-z][.?!,][A-Z]'
+  - '[\w.?!,\(\)\-":] {2,}[\w.?!,\(\)\-":]'

doc/.vale/gitlab/Substitutions.yml

@@ -0,0 +1,13 @@
+---
+# Checks for use of some of the top misused terms at GitLab.
+#
+# For a list of all options, see https://errata-ai.github.io/vale/styles/
+extends: substitution
+message: Use "%s" instead of "%s".
+link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+level: error
+ignorecase: true
+swap:
+  GitLabber: GitLab team member
+  self hosted: self-managed
+  self-hosted: self-managed

doc/README.md

@@ -33,9 +33,9 @@ This section describes the commonly used configuration settings. Check
 
 - [Installing GitLab](https://about.gitlab.com/install/)
   - [Manually downloading and installing a GitLab package](manual_install.md)
-- [Setting up a domain name/URL](https://docs.gitlab.com/omnibus/settings/configuration.html#configuring-the-external-url-for-gitlab) for the GitLab Instance so that it can be accessed easily
+- [Setting up a domain name/URL](settings/configuration.md#configuring-the-external-url-for-gitlab) for the GitLab Instance so that it can be accessed easily
-- [Enabling HTTPS](https://docs.gitlab.com/omnibus/settings/nginx.html#enable-https)
+- [Enabling HTTPS](settings/nginx.md#enable-https)
-- [Enabling notification emails](https://docs.gitlab.com/omnibus/settings/smtp.html#smtp-settings)
+- [Enabling notification emails](settings/smtp.md#smtp-settings)
 - [Enabling replying via email](https://docs.gitlab.com/ee/administration/reply_by_email.html#set-it-up)
   - [Installing and configuring postfix](https://docs.gitlab.com/ee/administration/reply_by_email_postfix_setup.html)
 - [Enabling container registry on GitLab](https://docs.gitlab.com/ee/administration/packages/container_registry.html#container-registry-domain-configuration)
@@ -74,8 +74,8 @@ to work best with the available resources. Check out the [documentation](setting
 - [Changing the name of the Git user group](settings/configuration.md#changing-the-name-of-the-git-user--group)
 - [Specify numeric user and group identifiers](settings/configuration.md#specify-numeric-user-and-group-identifiers)
 - [Only start Omnibus GitLab services after a given filesystem is mounted](settings/configuration.md#only-start-omnibus-gitlab-services-after-a-given-filesystem-is-mounted)
-- [Disable user and group account management](settings/configuration.html#disable-user-and-group-account-management)
+- [Disable user and group account management](settings/configuration.md#disable-user-and-group-account-management)
-- [Disable storage directory management](settings/configuration.html#disable-storage-directories-management)
+- [Disable storage directory management](settings/configuration.md#disable-storage-directories-management)
 - [Configuring Rack attack](settings/configuration.md#configuring-rack-attack)
 - [SMTP](settings/smtp.md)
 - [NGINX](settings/nginx.md)

doc/architecture/README.md

@@ -161,7 +161,7 @@ The cache mechanism can be summarised as follows:
    1. If cache has been dirtied, break the loop.
    1. Else, checkout the snapshot.
 1. If there are remaining dependencies:
-   1. For each remaining  dependency:
+   1. For each remaining dependency:
       1. Build the dependency.
       1. Create a snapshot and commit it.
 1. Push back the new build cache to CI cache.

doc/common_installation_problems/README.md

@@ -222,7 +222,7 @@ Keep in mind that the Git user must have access to the system so please review
 your security settings at `/etc/security/access.conf` and make sure the Git user
 is not blocked.
 
-## Postgres error 'FATAL:  could not create shared memory segment: Cannot allocate memory'
+## Postgres error `FATAL:  could not create shared memory segment: Cannot allocate memory`
 
 The packaged Postgres instance will try to allocate 25% of total memory as
 shared memory. On some Linux (virtual) servers, there is less shared memory
@@ -245,7 +245,7 @@ postgresql['shared_buffers'] = "100MB"
 
 Run `sudo gitlab-ctl reconfigure` for the change to take effect.
 
-## Postgres error 'FATAL:  could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied'
+## Postgres error `FATAL:  could not open shared memory segment "/PostgreSQL.XXXXXXXXXX": Permission denied`
 
 By default, Postgres will try to detect the shared memory type to use. If you don't
 have shared memory enabled, you might see this error in `/var/log/gitlab/postgresql/current`.
@@ -380,7 +380,7 @@ Redis, Mattermost) are isolated from each other using Unix user
 accounts. Creating and managing these user accounts requires root
 access. By default, Omnibus GitLab will create the required Unix
 accounts during `gitlab-ctl reconfigure` but that behavior can be
-[disabled](../settings/configuration.html#disable-user-and-group-account-management).
+[disabled](../settings/configuration.md#disable-user-and-group-account-management).
 
 In principle Omnibus GitLab could do with only 2 user accounts (one
 for GitLab and one for Mattermost) if we give each application its own
@@ -618,7 +618,7 @@ will need to switch to using `no_root_squash` in your NFS exports on the NFS ser
 This applies to operating systems using systemd (e.g. Ubuntu 16.04+, CentOS, etc.).
 
 Since GitLab 11.2, the `gitlab-runsvdir` starts during the `multi-user.target`
-instead of `basic.target`.  If you are having trouble starting this service
+instead of `basic.target`. If you are having trouble starting this service
 after upgrading GitLab, you may need to check that your system has properly
 booted all the required services for `multi-user.target` via the command:
 

doc/development/new-services.md

@@ -56,7 +56,7 @@ In `files/gitlab-cookbooks/package/libraries/config/gitlab.rb` you will find the
 `attribute` methods.
 
 If your service exists within the attributes for the GitLab cookbook, you should
-add it within the `attribute_block('gitlab')` block.  Otherwise, if your service
+add it within the `attribute_block('gitlab')` block. Otherwise, if your service
 has its own cookbook, add it above.
 
 Add your service as an attribute, using an underscore to separate words, **even if you

doc/development/new-software-definition.md

@@ -17,7 +17,7 @@ repositories of the local mirror and upstream should be added to
 `/.custom_sources.yml`.
 
 The local mirror should be created in the <https://dev.gitlab.org/omnibus-mirror>
-project by a member of the Distribution team.  It should have the
+project by a member of the Distribution team. It should have the
 `omnibus-builder deploy key` enabled.
 
 See other Software services in the directory for examples on how to include your

doc/manual_install.md

@@ -33,10 +33,10 @@ With the desired package downloaded, use your systems package management tool to
 
 Change `http://gitlab.example.com` to the URL at which you want to access your GitLab instance. Installation will automatically configure and start GitLab at that URL.
 
-> **Note:** Enabling HTTPS will require [additional configuration](settings/nginx.html#enable-https) to specify the certificates.
+> **Note:** Enabling HTTPS will require [additional configuration](settings/nginx.md#enable-https) to specify the certificates.
 
 ## Browse to the hostname and login
 
 On your first visit, you'll be redirected to a password reset screen. Provide the password for the initial administrator account and you will be redirected back to the login screen. Use the default account's username `root` to login.
 
-See our [documentation for detailed instructions on installing and configuration](https://docs.gitlab.com/omnibus/README.html#installation-and-configuration-using-omnibus-package).
+See our [documentation for detailed instructions on installing and configuration](README.md#installation-and-configuration-using-omnibus-package).

doc/package-information/README.md

@@ -20,7 +20,7 @@ These defauts are noted in the package [defaults document](defaults.md).
 ## Checking the versions of bundled software
 
 Once the Omnibus GitLab package is installed, all versions of the bundled
-libraries are  located in `/opt/gitlab/version-manifest.txt`.
+libraries are located in `/opt/gitlab/version-manifest.txt`.
 
 If you don't have the package installed, you can always check the Omnibus GitLab
 [source repository], specifically the [config directory].

doc/settings/backups.md

@@ -32,7 +32,7 @@ sudo crontab -e -u root
 The cron table will appear in an editor.
 
 Enter the command to create a compressed tar file containing the contents of
-`/etc/gitlab/`.  For example, schedule the backup to run every morning after a
+`/etc/gitlab/`. For example, schedule the backup to run every morning after a
 weekday, Tuesday (day 2) through Saturday (day 6):
 
 ```

doc/settings/configuration.md

@@ -649,7 +649,7 @@ details.
 GitLab 12.2 added support for [CSP and nonces with inline
 JavaScript](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src).
 It is [not configured on by default
-yet](https://gitlab.com/gitlab-org/gitlab/issues/30720).  An example
+yet](https://gitlab.com/gitlab-org/gitlab/issues/30720). An example
 configuration that will work for most installations of GitLab is below:
 
 ```ruby

doc/settings/environment-variables.md

@@ -1,9 +1,9 @@
 # Setting custom environment variables
 
 If necessary you can set custom environment variables to be used by Unicorn,
-Sidekiq, Rails and Rake via `/etc/gitlab/gitlab.rb`.  This can be useful in
+Sidekiq, Rails and Rake via `/etc/gitlab/gitlab.rb`. This can be useful in
 situations where you need to use a proxy to access the internet and need to
-clone externally hosted repositories directly into GitLab.  In
+clone externally hosted repositories directly into GitLab. In
 `/etc/gitlab/gitlab.rb` supply a `gitlab_rails['env']` with a hash value. For
 example:
 

doc/settings/nginx.md

@@ -327,7 +327,7 @@ nginx['listen_addresses'] = ["0.0.0.0", "[::]"] # listen on all IPv4 and IPv6 ad
 By default NGINX will listen on the port specified in `external_url` or
 implicitly use the right port (80 for HTTP, 443 for HTTPS). If you are running
 GitLab behind a reverse proxy, you may want to override the listen port to
-something else.  For example, to use port 8081:
+something else. For example, to use port 8081:
 
 ```ruby
 nginx['listen_port'] = 8081
@@ -336,7 +336,7 @@ nginx['listen_port'] = 8081
 ## Supporting proxied SSL
 
 By default NGINX will auto-detect whether to use SSL if `external_url`
-contains `https://`.  If you are running GitLab behind a reverse proxy, you
+contains `https://`. If you are running GitLab behind a reverse proxy, you
 may wish to terminate SSL at another proxy server or load balancer. To do this,
 be sure the `external_url` contains `https://` and apply the following
 configuration to `gitlab.rb`:
@@ -782,9 +782,9 @@ systems `sudo service nginx restart`).
 
 Make sure you don't have the `proxy_set_header` configuration in
 `nginx['custom_gitlab_server_config']` settings and instead use the
-['proxy_set_headers'](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl) configuration in your `gitlab.rb` file.
+['proxy_set_headers'](#supporting-proxied-ssl) configuration in your `gitlab.rb` file.
 
-### javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure
+### `javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure`
 
 Starting with GitLab 10, the Omnibus GitLab package no longer supports TLSv1 protocol by default.
 This can cause connection issues with some older Java based IDE clients when interacting with

doc/settings/ssl.md

@@ -15,7 +15,7 @@ Administrators can enable secure http using any method supported by a GitLab ser
 |-|-|-|
 | Primary GitLab Instance Domain | [Yes](nginx.md#manually-configuring-https) | [Yes](#lets-encrypt-integration) |
 | Container Registry | [Yes](https://docs.gitlab.com/ee/administration/packages/container_registry.html#configure-container-registry-under-its-own-domain) | [Yes](#lets-encrypt-integration) |
-| Mattermost | [Yes](https://docs.gitlab.com/omnibus/gitlab-mattermost/README.html#running-gitlab-mattermost-with-https) | [Yes](#lets-encrypt-integration) |
+| Mattermost | [Yes](../gitlab-mattermost/README.md#running-gitlab-mattermost-with-https) | [Yes](#lets-encrypt-integration) |
 | GitLab Pages | [Yes](https://docs.gitlab.com/ee/administration/pages/#wildcard-domains-with-tls-support) | No |
 
 ### Let's Encrypt Integration

doc/update/README.md

@@ -284,7 +284,7 @@ you've completed these steps.
 
 #### Using PostgreSQL HA
 
-Pick a node to be the `Deploy Node`.  It can be any node, but it must be the same
+Pick a node to be the `Deploy Node`. It can be any node, but it must be the same
 node throughout the process.
 
 **Deploy node**

doc/update/convert_to_omnibus.md

@@ -32,8 +32,8 @@ This assumes that `gitlab-shell` is located in `/home/git`.
 ## Upgrading from non-Omnibus PostgreSQL to an Omnibus installation in-place
 
 It is also possible to upgrade a source GitLab installation to Omnibus GitLab
-in-place.  Below we assume you are using PostgreSQL on Ubuntu, and that you
+in-place. Below we assume you are using PostgreSQL on Ubuntu, and that you
-have an Omnibus GitLab package matching your current GitLab version.  We also
+have an Omnibus GitLab package matching your current GitLab version. We also
 assume that your source installation of GitLab uses all the default paths and
 users.
 

doc/update/gitlab_10_changes.md

@@ -3,7 +3,7 @@
 From version 10.0 GitLab requires the version of PostgreSQL to be 9.6 or
 higher.
 
-Check out [docs on upgrading packaged PostgreSQL server](https://docs.gitlab.com/omnibus/settings/database.html#upgrade-packaged-postgresql-server)
+Check out [docs on upgrading packaged PostgreSQL server](../settings/database.md#upgrade-packaged-postgresql-server)
 for details.
 
 - For users running versions below 8.15 and using PostgreSQL bundled with

doc/update/gitlab_11_changes.md

@@ -45,14 +45,14 @@ been removed:
 
 1. Mattermost related configurations - Support for most of the Mattermost
    related configuration have been removed, except for the essential ones that
-   are needed for GitLab-Mattermost integration. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/gitlab-mattermost/#upgrading-gitlab-mattermost-from-versions-prior-to-11-0)
+   are needed for GitLab-Mattermost integration. [Check out the official documentation for details](../gitlab-mattermost/README.md#upgrading-gitlab-mattermost-from-versions-prior-to-110)
 
 1. Legacy `git_data_dir` configuration, which was used to set location of where
    data was to be stored. It has been now replaced with `git_data_dirs`
-   configuration. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory)
+   configuration. [Check out the official documentation for details](../settings/configuration.md#storing-git-data-in-an-alternative-directory)
 
 1. Old format of `git_data_dirs` configuration has been replaced with a new
-   format, allowing much more fine grain control. [Check out the official documentation for details](https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory)
+   format, allowing much more fine grain control. [Check out the official documentation for details](../settings/configuration.md#storing-git-data-in-an-alternative-directory)
 
 ## Changes introduced in minor versions
 
@@ -72,7 +72,7 @@ Rack Attack is disabled by default. To continue using Rack Attack, you must [ena
 
    For users looking for preserving the Prometheus version 1 data, a command
    line tool is provided to upgrade their Prometheus service and migrate data to
-   the format supported by new Prometheus version.  This tool can be invoked
+   the format supported by new Prometheus version. This tool can be invoked
    using the following command:
 
    ```bash
@@ -81,7 +81,7 @@ Rack Attack is disabled by default. To continue using Rack Attack, you must [ena
 
    This tool will convert existing data to a format supported by the latest
    Prometheus version. Depending on the volume of data, this process can take
-   hours.  If users do not want to migrate the data, but start with a clean
+   hours. If users do not want to migrate the data, but start with a clean
    database, they can pass `--skip-data-migration` flag to the above command.
 
    NOTE: **Note**: Prometheus service will be stopped during the migration process.

doc/update/gitlab_12_changes.md

@@ -8,7 +8,7 @@ When upgrading to a new major version, remember to first [check for background m
 Prometheus 1.x was deprecated in GitLab 11.4, and
 Prometheus 2.8.1 was installed by default on new installations. Users updating
 from older versions of GitLab could manually upgrade Prometheus data using the
-[`gitlab-ctl prometheus-upgrade`](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html#114)
+[`gitlab-ctl prometheus-upgrade`](gitlab_11_changes.md#114)
 command provided. You can view current Prometheus version in use from the
 instances Prometheus `/status` page.
 
@@ -16,7 +16,7 @@ With GitLab 12.0, support for Prometheus 1.x is completely removed, and as part
 of the upgrade process, Prometheus binaries will be updated to version 2.8.1.
 Existing data from Prometheus 1.x installation WILL NOT be migrated as part of
 this automatic upgrade, and users who wish to retain that data should
-[manually upgrade Prometheus version](https://docs.gitlab.com/omnibus/update/gitlab_11_changes.html#114)
+[manually upgrade Prometheus version](gitlab_11_changes.md#114)
 before upgrading to GitLab 12.0
 
 For users who use `/etc/gitlab/skip-auto-reconfigure` file to skip automatic
@@ -110,7 +110,7 @@ ones at the earliest.
 The Redis version packaged with Omnibus GitLab has been updated to Redis 5.0.7.
 You will need to restart Redis after the upgrade so that the new version will be
 active. To restart Redis, run `sudo gitlab-ctl restart redis`. If your instance
-has Redis HA with Sentinel, follow the upgrade steps documented in [Updating GitLab installed with the Omnibus GitLab package](https://docs.gitlab.com/omnibus/update/README.html#using-redis-ha-using-sentinel)
+has Redis HA with Sentinel, follow the upgrade steps documented in [Updating GitLab installed with the Omnibus GitLab package](README.md#using-redis-ha-using-sentinel)
 to avoid downtime.
 
 ### 12.8

gitlab-ci-config/gitlab-com.yml

@@ -135,6 +135,8 @@ docs-lint:
   before_script: []
   <<: *dedicated-runner
   script:
+    # Lint prose
+    - vale --minAlertLevel error doc
     # Lint Markdown
     - markdownlint --config .markdownlint.json 'doc/**/*.md'
     # Prepare docs for build