Merge branch 'eread/synchronize-linting-rules-docs' into 'master'

Synchronize lint rules and fix where required

See merge request gitlab-org/omnibus-gitlab!4486

doc/.vale/gitlab/Acronyms.yml

@@ -68,6 +68,7 @@ exceptions:
   - SSH
   - SSL
   - SSO
+  - SVG
   - SVN
   - TCP
   - TIP

doc/.vale/gitlab/AlertBoxStyle.yml

@@ -5,7 +5,7 @@
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
-message: 'Alert box "%s" must use the formatting detailed in the documentation style guide.'
+message: 'Alert box "%s" must use the formatting in the style guide.'
 link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes
 level: error
 scope: raw
@@ -13,4 +13,4 @@ raw:
   - '((NOTE|TIP|CAUTION|DANGER): \*\*[^:]*\*\*)|'
   - '((NOTE: \*\*(NOTE|note):\*\*)|(TIP: \*\*(TIP|tip):\*\*)|(CAUTION: \*\*(CAUTION|caution):\*\*)|(DANGER: \*\*(DANGER|danger):\*\*))|'
   - '((NOTE|TIP|CAUTION|DANGER): \*\*.*\*\*.+)|'
-  - '((\n[ ]*(\*){1,2}(NOTE|Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger):(\*){1,2})'
+  - '((\n[> ]*(\*){1,2}(NOTE|Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger):(\*){1,2}))'

doc/.vale/gitlab/FutureTense.yml

@@ -11,7 +11,7 @@ ignorecase: true
 level: warning
 link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid
 raw:
-   - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
-   - "will( |\n|[[:punct:]])[a-zA-Z]*|"
-   - "won't( |\n|[[:punct:]])[a-zA-Z]*|"
-   - "[a-zA-Z]*'ll( |\n|[[:punct:]])[a-zA-Z]*)"
+  - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
+  - "will( |\n|[[:punct:]])[a-zA-Z]*|"
+  - "won't( |\n|[[:punct:]])[a-zA-Z]*|"
+  - "[a-zA-Z]*'ll( |\n|[[:punct:]])[a-zA-Z]*)"

doc/.vale/gitlab/spelling-exceptions.txt

@@ -191,6 +191,7 @@ http
 https
 idempotence
 idmapper
+inclusivity
 Ingress
 initializer
 initializers
@@ -308,6 +309,8 @@ Piwik
 PgBouncer
 plaintext
 Poedit
+polyfill
+polyfills
 pooler
 PostgreSQL
 precompile
@@ -385,6 +388,7 @@ reverify
 Rubix
 Rubocop
 Rubular
+ruleset
 runbook
 runbooks
 runit

doc/build/README.md

@@ -6,7 +6,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # Building `omnibus-gitlab` packages and Docker images locally
-NOTE: **Note**
+NOTE: **Note:**
 If you are a GitLab team member, you have access to our CI infrastructure which
 can be used to build these artifacts. Check the [documentation](team_member_docs.md)
 for more details.
@@ -24,7 +24,7 @@ How to build a custom package locally is described in the
 ## All-in-one Docker image
-NOTE: **Note**:
+NOTE: **Note:**
 If you want individual Docker images for each GitLab component instead of the
 all-in-one monolithic one, check out the
 [CNG](https://gitlab.com/gitlab-org/build/CNG) repository.

doc/common_installation_problems/README.md

@@ -111,19 +111,18 @@ Try [specifying](../settings/configuration.md#configuring-the-external-url-for-g
 `/etc/gitlab/gitlab.rb`. Also check your firewall settings; port 80 (HTTP) or
 443 (HTTPS) might be closed on your GitLab server.
-> **Note:**
-> Specifying the `external_url` for GitLab, or any other bundled service
-> (Registry and Mattermost) doesn't follow the `key=value` format that other
-> parts of `gitlab.rb` follow. Make sure that you have them set in the following
-> format:
->
-> ```ruby
-> external_url "https://gitlab.example.com"
-> registry_external_url "https://registry.example.com"
-> mattermost_external_url "https://mattermost.example.com"
-> ```
->
-> **Don't add the equal sign (`=`) between `external_url` and the value.**
+Note that specifying the `external_url` for GitLab, or any other bundled service (Registry and
+Mattermost) doesn't follow the `key=value` format that other parts of `gitlab.rb` follow. Make sure
+that you have them set in the following format:
+
+```ruby
+external_url "https://gitlab.example.com"
+registry_external_url "https://registry.example.com"
+mattermost_external_url "https://mattermost.example.com"
+```
+
+NOTE: **Note:**
+Don't add the equal sign (`=`) between `external_url` and the value.
 ## Emails are not being delivered

doc/development/README.md

@@ -69,7 +69,8 @@ their applicability:
 1. If Merge Request introduces change in user facing configuration, update to [`gitlab.rb.template`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template)
 1. [Changelog entry](https://docs.gitlab.com/ee/development/changelog.html) to inform about the change, if necessary.
-**Note:** Ensure shared runners are enabled for your fork in order for our automated tests to run:
+NOTE: **Note:**
+Ensure shared runners are enabled for your fork in order for our automated tests to run:
 1. Go to Settings -> CI/CD
 1. Expand Runners settings

doc/development/pipelines.md

@@ -19,8 +19,9 @@ between all the mirrors of the project:
 ### Protected branches
-NOTE: **Note:** Unless specified otherwise, the listed users/groups have
-permission to both merge, and push to protected branches.
+NOTE: **Note:**
+Unless specified otherwise, the listed users/groups have permission to both merge, and push to
+protected branches.
 1. Development repository
     1. `master`: Maintainers, [Delivery team](https://gitlab.com/gitlab-org/delivery)
@@ -43,15 +44,17 @@ permission to both merge, and push to protected branches.
 1. QA mirror:
     1. `master`: Developers (Merge only), Maintainers
-NOTE: **Note:** Developers get access to `master` branch in QA mirror because
+NOTE: **Note:**
+Developers get access to `master` branch in QA mirror because
 that's required to run a triggered pipeline against the branch. There is an
 [open issue](https://gitlab.com/gitlab-org/gitlab/-/issues/24585) to change this
 situation.
 ### Protected Tags
-NOTE: **Note:** Unless specified otherwise, the listed users/groups have
-permission to both merge, and push to protected tags.
+NOTE: **Note:**
+Unless specified otherwise, the listed users/groups have permission to both merge, and push to
+protected tags.
 1. Development repository:
     1. `*` : Maintainers, [Delivery team](https://gitlab.com/gitlab-org/delivery), [Release Managers](https://gitlab.com/gitlab-org/release/managers)
@@ -320,8 +323,8 @@ to an S3 bucket in addition to making them available as artifacts.
 This job is run only on [Release mirror](https://dev.gitlab.org/gitlab/omnibus-gitlab) on tag pipelines.
-NOTE: **Note:** Raspberry Pi jobs are run only on CE tags while SLES jobs are run only
-on EE tags.
+NOTE: **Note:**
+Raspberry Pi jobs are run only on CE tags while SLES jobs are run only on EE tags.
 ### `<OS_NAME>-staging`
@@ -330,8 +333,8 @@ repository in [Packagecloud instance](https://packages.gitlab.com).
 This job is run only on [Release mirror](https://dev.gitlab.org/gitlab/omnibus-gitlab) on tag pipelines.
-NOTE: **Note:** Raspberry Pi jobs are run only on CE tags while SLES jobs are run only
-on EE tags.
+NOTE: **Note:**
+Raspberry Pi jobs are run only on CE tags while SLES jobs are run only on EE tags.
 ### `<OS_NAME>-release`
@@ -340,8 +343,8 @@ repository in [Packagecloud instance](https://packages.gitlab.com).
 This job is run only on [Release mirror](https://dev.gitlab.org/gitlab/omnibus-gitlab) on tag pipelines.
-NOTE: **Note:** Raspberry Pi jobs are run only on CE tags while SLES jobs are run only
-on EE tags.
+NOTE: **Note:**
+Raspberry Pi jobs are run only on CE tags while SLES jobs are run only on EE tags.
 ### `Docker`

doc/gitlab-mattermost/README.md

@@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # GitLab Mattermost
-NOTE: **Note:** This document applies to GitLab 11.0 and later.
+NOTE: **Note:**
+This document applies to GitLab 11.0 and later.
 You can run a [GitLab Mattermost](https://gitlab.com/gitlab-org/gitlab-mattermost)
 service on your GitLab server.

doc/package-information/defaults.md

@@ -67,4 +67,5 @@ Note that if you are using NFS (Network File System), files will be carried
 over a network which will require, based on implementation, ports `111` and
 `2049` to be open.
-NOTE: **Note:** In some cases, the GitLab Registry will be automatically enabled by default. Please see [our documentation](https://docs.gitlab.com/ee/administration/packages/container_registry.html) for more details
+NOTE: **Note:**
+In some cases, the GitLab Registry will be automatically enabled by default. Please see [our documentation](https://docs.gitlab.com/ee/administration/packages/container_registry.html) for more details

doc/settings/actioncable.md

@@ -6,7 +6,8 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 # ActionCable
-NOTE: **Note:** ActionCable is **experimental** and the features that use this service are behind feature flags.
+NOTE: **Note:**
+ActionCable is **experimental** and the features that use this service are behind feature flags.
 This service is disabled by default. To enable:

doc/settings/backups.md

@@ -23,11 +23,13 @@ configuration, just run `sudo gitlab-ctl backup-etc`. It will create a tar
 archive in `/etc/gitlab/config_backup/`. Directory and backup files will be
 readable only to root.
-NOTE: **Note**: Running `sudo gitlab-ctl backup-etc <DIRECTORY>` will place
+NOTE: **Note:**
+Running `sudo gitlab-ctl backup-etc <DIRECTORY>` will place
 the backup in the specified directory. The directory will be created if it
 does not exist. Absolute paths are recommended.
-NOTE: **Note:** `backup-etc` introduced in GitLab 12.3.
+NOTE: **Note:**
+`backup-etc` introduced in GitLab 12.3.
 To create a daily application backup, edit the cron table for user root:
@@ -57,7 +59,8 @@ sudo tar -xf gitlab_config_1487687824_2017_02_21.tar -C /
 Remember to run `sudo gitlab-ctl reconfigure` after restoring a configuration
 backup.
-NOTE: Your machines SSH host keys are stored in a separate location at `/etc/ssh/`. Be sure to also [backup and restore those keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) to avoid man-in-the-middle attack warnings if you have to perform a full machine restore.
+NOTE: **Note:**
+Your machines SSH host keys are stored in a separate location at `/etc/ssh/`. Be sure to also [backup and restore those keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079) to avoid man-in-the-middle attack warnings if you have to perform a full machine restore.
 ### Separate configuration backups from application data
@@ -105,7 +108,7 @@ Backup configuration and secrets:
 docker exec -t <your container name> /bin/sh -c 'umask 0077; tar cfz /secret/gitlab/backups/$(date "+etc-gitlab-\%s.tgz") -C / etc/gitlab'
 ```
->**Note:**
+NOTE: **Note:**
 You need to have volumes mounted at `/secret/gitlab/backups` and `/var/opt/gitlab`
 in order to have these backups persisted outside the container.

doc/settings/database.md

@@ -317,9 +317,9 @@ To opt out of automatic PostgreSQL upgrade during GitLab package upgrades, run:
 sudo touch /etc/gitlab/disable-postgresql-upgrade
 ```
-If you want to manually upgrade without upgrading GitLab, you can follow these instructions:
-**Note:**
+If you want to manually upgrade without upgrading GitLab, you can follow these instructions.
+Take note of the following:
 - Please fully read this section before running any commands.
 - Please plan ahead as upgrade involves downtime.
@@ -498,7 +498,7 @@ sure that PostgreSQL is set up according to the [database requirements document]
    Don't forget to remove the `#` comment characters at the beginning of these
    lines.
-   **Note:**
+   Note that:
    - `/etc/gitlab/gitlab.rb` should have file permissions `0600` because it contains
      plain-text passwords.
@@ -528,7 +528,8 @@ instead of the one bundled with GitLab, you can do so by using a UNIX socket:
    gitlab_rails['db_host'] = '/var/run/postgresql/'
    ```
-   NOTE: **Note:** `gitlab_rails['db_socket']` is a setting for Mysql and it won't have any effect on PostgreSQL.
+   NOTE: **Note:**
+   `gitlab_rails['db_socket']` is a setting for Mysql and it won't have any effect on PostgreSQL.
 1. Reconfigure GitLab for the changes to take effect:

doc/settings/dns.md

@@ -10,13 +10,15 @@ While it is possible to run a GitLab instance using only IP addresses, it can be
 Adding these entries to your domain's DNS configuration is entirely dependent on your chosen provider, and out of scope for this document. Consult the documentation from your domain name registrar, hosting provider, or managed DNS provider for the most accurate guidance.
-NOTE: **Note:** Unless you want to take advantage of the [Let's Encrypt integration](ssl.md#lets-encrypt-integration), it is not required that any of these addresses are resolvable over the public internet. It is only required that nodes that will access the GitLab instance be able to resolve the addresses.
+NOTE: **Note:**
+Unless you want to take advantage of the [Let's Encrypt integration](ssl.md#lets-encrypt-integration), it is not required that any of these addresses are resolvable over the public internet. It is only required that nodes that will access the GitLab instance be able to resolve the addresses.
 ## GitLab Settings
 Below is a list of attributes for `/etc/gitlab/gitlab.rb` that can take advantage of a corresponding DNS entry.
-NOTE: **Note:** It is possible to replace the below DNS entries with a wildcard entry in DNS. However, you will still need to provide your GitLab instance with the individual records, and this will **not** result in the Let's Encrypt integration fetching a wildcard certificate.
+NOTE: **Note:**
+It is possible to replace the below DNS entries with a wildcard entry in DNS. However, you will still need to provide your GitLab instance with the individual records, and this will **not** result in the Let's Encrypt integration fetching a wildcard certificate.
 ### `external_url`

doc/settings/environment-variables.md

@@ -49,20 +49,24 @@ registry['env'] = {
 }
 ```
-NOTE: **Note:** The `no_proxy` entry for Gitaly is needed in GitLab 11.6
+NOTE: **Note:**
+The `no_proxy` entry for Gitaly is needed in GitLab 11.6
 and newer if a proxy is defined and Gitaly is listening on a UNIX
 socket, which it is by default. It appears to be a limitation in the
 gRPC client library. See [the Gitaly
 issue](https://gitlab.com/gitlab-org/gitaly/-/issues/1447) for more
 details.
-NOTE: **Note:** GitLab 11.6 and newer will attempt to use HTTP Basic
+NOTE: **Note:**
+GitLab 11.6 and newer will attempt to use HTTP Basic
 Authentication when a username and password is included in the proxy
 URL. Older GitLab versions will omit the authentication details.
-NOTE: **Note:** Proxy settings use the `.` syntax for globing.
-NOTE: **Note:** Proxy URL values should generally be `http://` only, unless
+NOTE: **Note:**
+Proxy settings use the `.` syntax for globing.
+NOTE: **Note:**
+Proxy URL values should generally be `http://` only, unless
 your proxy has its own SSL certificate and SSL enabled. This means, even for
 the `https_proxy` value, you should usually specify a value as
 `http://USERNAME:PASSWORD@example.com:8080`.
@@ -72,7 +76,8 @@ the `https_proxy` value, you should usually specify a value as
 Any change made to the environment variables **requires a hard restart** after
 reconfigure for it to take effect.
-NOTE: **Note**: During a hard restart, your GitLab instance will be down until the
+NOTE: **Note:**
+During a hard restart, your GitLab instance will be down until the
 services are back up.
 For configurations where Puma is enabled, only a reconfigure is necessary since

doc/settings/logs.md

@@ -98,7 +98,8 @@ nginx['logrotate_size'] = "200M"
 logrotate['enable'] = false
 ```
-NOTE: **Note:** Currently the Gitaly-specific [GitLab Shell log](https://docs.gitlab.com/ee/administration/logs.html#gitlab-shelllog) is not rotated by logrotate.
+NOTE: **Note:**
+Currently the Gitaly-specific [GitLab Shell log](https://docs.gitlab.com/ee/administration/logs.html#gitlab-shelllog) is not rotated by logrotate.
 See [Issue #4938](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4938) for more details.
 ### Run logrotate manually
@@ -122,7 +123,8 @@ logging['udp_log_shipping_host'] = '1.2.3.4' # Your syslog server
 logging['udp_log_shipping_port'] = 1514 # Optional, defaults to 514 (syslog)
 ```
-NOTE: **Note:** Setting `udp_log_shipping_host` will [add a `svlogd_prefix`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/logging.rb)
+NOTE: **Note:**
+Setting `udp_log_shipping_host` will [add a `svlogd_prefix`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/logging.rb)
 for the specified hostname and service for each of the [runit-managed](../architecture/README.md#runit) services.
 Example log messages:
@@ -158,7 +160,8 @@ Splunk, or another log management system.
 [Beginning in Omnibus GitLab 12.0](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4102),
 the JSON format is enabled by default for all services that support it.
-NOTE: **Note** PostgreSQL does not support JSON logging without an
+NOTE: **Note:**
+PostgreSQL does not support JSON logging without an
 external plugin. However, it does support logging in CSV format:
 ```ruby
@@ -185,4 +188,5 @@ sidekiq['log_format'] = 'default'
 gitlab_pages['log_format'] = 'text'
 ```
-NOTE: **Note:** There are a few variations in attribute names for the log format depending on the service involved (for example, Container Registry uses `log_formatter`, Gitaly and Praefect both use `logging_format`). See [Issue #4280](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4280) for more details.
+NOTE: **Note:**
+There are a few variations in attribute names for the log format depending on the service involved (for example, Container Registry uses `log_formatter`, Gitaly and Praefect both use `logging_format`). See [Issue #4280](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/4280) for more details.

doc/settings/nginx.md

@@ -28,7 +28,8 @@ registry_nginx['redirect_http_to_https'] = true
 mattermost_nginx['redirect_http_to_https'] = true
 ```
-NOTE: **Note:** Modifying NGINX configuration should be done with care as incorrect
+NOTE: **Note:**
+Modifying NGINX configuration should be done with care as incorrect
 or incompatible configuration may yield to unavailability of service.
 ## Enable HTTPS
@@ -114,7 +115,8 @@ no longer listen for unencrypted HTTP traffic on port 80. If you want to
 redirect all HTTP traffic to HTTPS you can use the `redirect_http_to_https`
 setting.
-NOTE: **Note:** This behavior is enabled by default.
+NOTE: **Note:**
+This behavior is enabled by default.
 ```ruby
 external_url "https://gitlab.example.com"
@@ -242,7 +244,8 @@ nginx['http2_enabled'] = false
 Save the file and [reconfigure GitLab](https://docs.gitlab.com/ee/administration/restart_gitlab.html#omnibus-gitlab-reconfigure)
 for the changes to take effect.
-NOTE: **Note:** The `http2` setting only works for the main GitLab application and not for the other services.
+NOTE: **Note:**
+The `http2` setting only works for the main GitLab application and not for the other services.
 ## Using a non-bundled web-server
@@ -400,7 +403,8 @@ Setting `max_age` to 0 will disable this feature. For more information see:
 - <https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/>
-NOTE: **Note:** The HSTS settings only work for the main GitLab application and not for the other services.
+NOTE: **Note:**
+The HSTS settings only work for the main GitLab application and not for the other services.
 ## Setting the Referrer-Policy header
@@ -434,7 +438,8 @@ disable this behavior:
 nginx['gzip_enabled'] = false
 ```
-NOTE: **Note:** The `gzip` setting only works for the main GitLab application and not for the other services.
+NOTE: **Note:**
+The `gzip` setting only works for the main GitLab application and not for the other services.
 ## Using custom SSL ciphers
@@ -557,7 +562,8 @@ In some cases you may want to host GitLab using an existing Passenger/NGINX
 installation but still have the convenience of updating and installing using
 the omnibus packages.
-NOTE: **Note:** When disabling NGINX, you won't be able to access
+NOTE: **Note:**
+When disabling NGINX, you won't be able to access
 other services included by Omnibus, like Grafana, Mattermost, etc. unless
 you manually add them in `nginx.conf`.
@@ -585,7 +591,8 @@ web_server['external_users'] = ['www-data']
 Make sure you run `sudo gitlab-ctl reconfigure` for the changes to take effect.
-**Note:** If you are running a version older than 8.16.0, you will have to
+NOTE: **Note:**
+If you are running a version older than 8.16.0, you will have to
 manually remove the Unicorn service file (`/opt/gitlab/service/unicorn`), if
 exists, for reconfigure to succeed.
@@ -726,13 +733,14 @@ server {
 Don't forget to update `git.example.com` in the above example to be your server URL.
-**Note:** If you wind up with a 403 forbidden, it's possible that you haven't enabled passenger in `/etc/nginx/nginx.conf`, to do so simply uncomment:
+If you wind up with a 403 forbidden, it's possible that you haven't enabled passenger in `/etc/nginx/nginx.conf`,
+to do so simply uncomment:
 ```plaintext
 # include /etc/nginx/passenger.conf;
 ```
-then, `sudo service nginx reload`
+Then run `sudo service nginx reload`.
 ## Enabling/Disabling nginx_status

doc/settings/redis.md

@@ -46,10 +46,10 @@ issues) for use with GitLab you can do so using Omnibus GitLab.
 ### Setting up the Redis Node
-> **Note:** Redis does not require authentication by default. See
-> [Redis Security](https://redis.io/topics/security) documentation for more
-> information. We recommend using a combination of a Redis password and tight
-> firewall rules to secure your Redis service.
+NOTE: **Note:**
+Redis does not require authentication by default. See [Redis Security](https://redis.io/topics/security)
+documentation for more information. We recommend using a combination of a Redis password and tight
+firewall rules to secure your Redis service.
 1. Download/install Omnibus GitLab using **steps 1 and 2** from
    [GitLab downloads](https://about.gitlab.com/install/). Do not complete other
@@ -72,9 +72,10 @@ issues) for use with GitLab you can do so using Omnibus GitLab.
    gitlab_rails['auto_migrate'] = false
    ```
-   > **Note:** The `redis_master_role['enable']` option is only available as of
-   > GitLab 8.14, see [`gitlab_rails.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb)
-   > to understand which services are automatically disabled via that option.
+   NOTE: **Note:**
+   The `redis_master_role['enable']` option is only available as of GitLab 8.14, see
+   [`gitlab_rails.rb`](https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-cookbooks/gitlab/libraries/gitlab_rails.rb)
+   to understand which services are automatically disabled via that option.
 1. Run `sudo gitlab-ctl reconfigure` to install and configure Redis.

doc/settings/smtp.md

@@ -10,7 +10,7 @@ If you would rather send application email via an SMTP server instead of via
 Sendmail, add the following configuration information to
 `/etc/gitlab/gitlab.rb` and run `gitlab-ctl reconfigure`.
->**Warning:**
+CAUTION: **Caution:**
 Your `smtp_password` should not contain any String delimiters used in
 Ruby or YAML (f.e. `'`) to avoid unexpected behavior during the processing of
 config settings.
@@ -62,7 +62,7 @@ gitlab_rails['smtp_force_ssl'] = false
 ### Gmail
->**Note:**
+NOTE: **Note:**
 Gmail has [strict sending limits](https://support.google.com/a/answer/166852)
 that can impair functionality as your organization grows. We strongly recommend using a
 transactional service like [SendGrid](https://sendgrid.com/) or [Mailgun](https://www.mailgun.com/)

doc/settings/ssl.md

@@ -34,7 +34,8 @@ GitLab can be integrated with [Let's Encrypt](https://letsencrypt.org).
 > - Enabled by default in GitLab 10.7 and later if `external_url` is set with
 >   the *https* protocol and no certificates are configured.
-NOTE: **Note**: In order for Let's Encrypt verification to work correctly, ports 80 and 443 will
+NOTE: **Note:**
+In order for Let's Encrypt verification to work correctly, ports 80 and 443 will
 need to be accessible to the Let's Encrypt servers that run the validation. Also note that the validation
 currently [does not work with non-standard ports](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/3580).
@@ -51,7 +52,7 @@ external_url "https://gitlab.example.com"         # Must use https protocol
 letsencrypt['contact_emails'] = ['foo@email.com'] # Optional
 ```
-TIP: **Maintenance Tip**
+TIP: **Tip:**
 Certificates issued by **Let's Encrypt** expire every ninety days. The optional `contact_emails`
 setting causes an expiration alert to be sent to the configured address when that expiration date approaches.
@@ -68,7 +69,7 @@ mattermost_external_url "https://mattermost.example.com" # mattermost, must use
 #registry_nginx['ssl_certificate'] = "path/to/cert"      # Must be absent or commented out
 ```
-NOTE: **Under the Hood**
+NOTE: **Note:**
 The **Let's Encrypt** certificate is created with the GitLab primary
 instance as the primary name on the certificate. Additional services
 such as the registry are added as alternate names to the same
@@ -122,7 +123,7 @@ If you plan to use your own **Let's Encrypt** certificate you must set `letsencr
 in `/etc/gitlab/gitlab.rb` to disable integration. **Otherwise the certificate
 could be overwritten due to the renewal.**
-TIP: **Tip**
+TIP: **Tip:**
 The above commands require root privileges and only generate a renewal if the certificate is close to expiration.
 [Consider the upstream rate limits](https://letsencrypt.org/docs/rate-limits/) if encountering an error during renewal.
@@ -142,10 +143,10 @@ certificate authenticity.
 Omnibus GitLab supports connections to external services with
 self-signed certificates.
-NOTE: **Compatibility Note**
+NOTE: **Note:**
 Custom certificates were introduced in GitLab 8.9.
-TIP: **Further Reading**
+TIP: **Tip:**
 For installations that use self-signed certificates, Omnibus-GitLab
 provides a way to manage these certificates. For more technical details how
 this works, see the [details](#details-on-how-gitlab-and-ssl-work)
@@ -179,11 +180,11 @@ this OpenSSL version.
 - Perform a test connection to the host over HTTPS. Replace `HOSTNAME` with your GitLab URL
   (excluding HTTPS), and replace `port` with the port that serves HTTPS connections (usually 443):
-  
+
   ```shell
   echo | /opt/gitlab/embedded/bin/openssl s_client -connect HOSTNAME:port
-  ```  
-  
+  ```
+
   The `echo` command sends a null request to the server, causing it to close the connection rather
   than wait for additional input. You can use the same command to test remote hosts (for example, a
   server hosting an external repository), by replacing `HOSTNAME:port` with the remote host's domain
@@ -266,7 +267,7 @@ ERROR: Not a certificate: /opt/gitlab/embedded/ssl/certs/FILE. Move it from /opt
 Check `/opt/gitlab/embedded/ssl/certs` and remove any files other than `README.md` that aren't valid X.509 certificates.
-NOTE: **Under the Hood**
+NOTE: **Note:**
 Running `gitlab-ctl reconfigure` constructs symlinks named from the subject hashes
 of your custom public certificates and places them in `/opt/gitlab/embedded/ssl/certs/`.
 Broken symlinks in `/opt/gitlab/embedded/ssl/certs/` will be automatically removed.