Merge branch 'docs-alert-box-new-rules' into 'master'

Add new vale rules to cover new alert box style

See merge request gitlab-org/gitlab!49918

doc/.vale/gitlab/AlertBoxStyle.yml

+---
+# Error: gitlab.AlertBoxStyle
+#
+# Makes sure alert boxes are used with block quotes.
+#
+# Checks for 3 formatting issues:
+# - Alert boxes inside a block quote (">")
+# - Alert boxes with the note text on the same line
+# - Alert boxes using words other than "NOTE" or "WARNING"
+#
+# 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 in the style guide.'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#alert-boxes
+level: error
+nonword: true
+scope: raw
+raw:
+  - '(\n *\> *(?:NOTE|WARNING)|'
+  - '\n(NOTE):[^\n]|'  # Adding "WARNING" here causes a false positive
+  - '\n *(?:> )?\**(Note|note|TIP|Tip|tip|CAUTION|Caution|caution|DANGER|Danger|danger|warning):.*)'  ## Adding "Warning" here causes a false positive

doc/administration/geo/replication/troubleshooting.md

@@ -308,7 +308,8 @@ log data to build up in `pg_xlog`. Removing the unused slots can reduce the amou
    sudo gitlab-psql
    ```
 
-   Note: Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
+   NOTE:
+   Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions.
 
 1. View your replication slots with:
 

doc/administration/operations/fast_ssh_key_lookup.md

@@ -28,7 +28,8 @@ GitLab Shell solves this by providing a way to authorize SSH users via a fast,
 indexed lookup in the GitLab database. This page describes how to enable the fast
 lookup of authorized SSH keys.
 
-> **Warning:** OpenSSH version 6.9+ is required because
+WARNING:
+OpenSSH version 6.9+ is required because
 `AuthorizedKeysCommand` must be able to accept a fingerprint. These
 instructions will break installations using older versions of OpenSSH, such as
 those included with CentOS 6 as of September 2017. If you want to use this

doc/administration/operations/ssh_certificates.md

@@ -19,7 +19,8 @@ user, including ones that expire 24 hours after issuing.
 In such setups some external automated process is needed to constantly
 upload the new keys to GitLab.
 
-> **Warning:** OpenSSH version 6.9+ is required because that version
+WARNING:
+OpenSSH version 6.9+ is required because that version
 introduced the `AuthorizedPrincipalsCommand` configuration option. If
 using CentOS 6, you can [follow these
 instructions](fast_ssh_key_lookup.html#compiling-a-custom-version-of-openssh-for-centos-6)

doc/administration/repository_storage_paths.md

@@ -40,27 +40,26 @@ storage2:
 
 ## Configure GitLab
 
-> **Warning:**
-> In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a
-> mount point and the GitLab user should have correct permissions for the parent
-> directory of the path. In Omnibus GitLab this is taken care of automatically,
-> but for source installations you should be extra careful.
->
-> The thing is that for compatibility reasons `gitlab.yml` has a different
-> structure than Omnibus. In `gitlab.yml` you indicate the path for the
-> repositories, for example `/home/git/repositories`, while in Omnibus you
-> indicate `git_data_dirs`, which for the example above would be `/home/git`.
-> Then, Omnibus creates a `repositories` directory under that path to use with
-> `gitlab.yml`.
->
-> This little detail matters because while restoring a backup, the current
-> contents of  `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`,
-> so if `/home/git/repositories` is the mount point, then `mv` would be moving
-> things between mount points, and bad things could happen. Ideally,
-> `/home/git` would be the mount point, so then things would be moving within the
-> same mount point. This is guaranteed with Omnibus installations (because they
-> don't specify the full repository path but the parent path), but not for source
-> installations.
+In order for [backups](../raketasks/backup_restore.md) to work correctly, the storage path must **not** be a
+mount point and the GitLab user should have correct permissions for the parent
+directory of the path. In Omnibus GitLab this is taken care of automatically,
+but for source installations you should be extra careful.
+
+The thing is that for compatibility reasons `gitlab.yml` has a different
+structure than Omnibus. In `gitlab.yml` you indicate the path for the
+repositories, for example `/home/git/repositories`, while in Omnibus you
+indicate `git_data_dirs`, which for the example above would be `/home/git`.
+Then, Omnibus creates a `repositories` directory under that path to use with
+`gitlab.yml`.
+
+This little detail matters because while restoring a backup, the current
+contents of `/home/git/repositories` [are moved to](https://gitlab.com/gitlab-org/gitlab/blob/033e5423a2594e08a7ebcd2379bd2331f4c39032/lib/backup/repository.rb#L54-56) `/home/git/repositories.old`,
+so if `/home/git/repositories` is the mount point, then `mv` would be moving
+things between mount points, and bad things could happen. Ideally,
+`/home/git` would be the mount point, so then things would be moving within the
+same mount point. This is guaranteed with Omnibus installations (because they
+don't specify the full repository path but the parent path), but not for source
+installations.
 
 Now that you've read that big fat warning above, let's edit the configuration
 files and add the full paths of the alternative repository storage paths. In

doc/administration/server_hooks.md

@@ -123,13 +123,13 @@ Within a directory, server hooks:
 - Are executed in alphabetical order.
 - Stop executing when a hook exits with a non-zero value.
 
-Note:
+`<hook_name>.d` must be either `pre-receive.d`, `post-receive.d`, or `update.d` to work properly.
+Any other names are ignored.
 
-- `<hook_name>.d` must be either `pre-receive.d`, `post-receive.d`, or `update.d` to work properly.
-  Any other names are ignored.
-- Files in `.d` directories must be executable and not match the backup file pattern (`*~`).
-- For `<project>.git` you need to [translate](repository_storage_types.md#translating-hashed-storage-paths)
-  your project name into the hashed storage format that GitLab uses.
+Files in `.d` directories must be executable and not match the backup file pattern (`*~`).
+
+For `<project>.git` you need to [translate](repository_storage_types.md#translating-hashed-storage-paths)
+your project name into the hashed storage format that GitLab uses.
 
 ## Environment Variables
 

doc/api/services.md

@@ -747,7 +747,8 @@ Send IRC messages, on update, to a list of recipients through an Irker gateway.
 
 Set Irker (IRC gateway) service for a project.
 
-> NOTE: Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>.
+NOTE:
+Irker does NOT have built-in authentication, which makes it vulnerable to spamming IRC channels if it is hosted outside of a firewall. Please make sure you run the daemon within a secured network to prevent abuse. For more details, read: <http://www.catb.org/~esr/irker/security.html>.
 
 ```plaintext
 PUT /projects/:id/services/irker

doc/ci/ci_cd_for_external_repos/bitbucket_integration.md

@@ -62,8 +62,9 @@ To use GitLab CI/CD with a Bitbucket Cloud repository:
 
 1. In Bitbucket, add a script to push the pipeline status to Bitbucket.
 
-   > Note: changes made in GitLab are overwritten by any changes made
-   > upstream in Bitbucket.
+   NOTE:
+   Changes made in GitLab are overwritten by any changes made
+   upstream in Bitbucket.
 
    Create a file `build_status` and insert the script below and run
    `chmod +x build_status` in your terminal to make the script executable.

doc/development/fe_guide/performance.md

@@ -188,7 +188,7 @@ All the marks and measures should be instantiated with the constants from
 `app/assets/javascripts/performance/constants.js`. When you’re ready to add a new mark’s or
 measurement’s label, you can follow the pattern.
 
-NOTE: **Note:**
+NOTE:
 This pattern is a recommendation and not a hard rule.
 
 ```javascript

doc/development/testing_guide/end_to_end/style_guide.md

@@ -74,7 +74,8 @@ We follow a simple formula roughly based on Hungarian notation.
   - `_tab`
   - `_menu_item`
 
-*Note: If none of the listed types are suitable, please open a merge request to add an appropriate type to the list.*
+NOTE:
+If none of the listed types are suitable, please open a merge request to add an appropriate type to the list.
 
 ### Examples
 

doc/install/installation.md

@@ -832,7 +832,7 @@ sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
 
 If all items are green, congratulations on successfully installing GitLab!
 
-TIP:  **Tip:**
+NOTE:
 Supply the `SANITIZE=true` environment variable to `gitlab:check` to omit project names from the output of the check command.
 
 ### Initial Login

doc/raketasks/features.md

@@ -12,11 +12,10 @@ This Rake task enables [namespaces](../user/group/index.md#namespaces) for proje
 
 This command enables the namespaces feature introduced in GitLab 4.0. It moves every project in its namespace folder.
 
-Note:
+The **repository location changes as part of this task**, so you must **update all your Git URLs** to
+point to the new location.
 
-- The **repository location changes as part of this task**, so you must **update all your Git URLs** to
-  point to the new location.
-- The username can be changed at **Profile > Account**.
+The username can be changed at **Profile > Account**.
 
 For example:
 

doc/update/upgrading_from_source.md

@@ -45,7 +45,7 @@ specific guidelines (should there be any) are covered separately.
 
 ### 1. Backup
 
-NOTE: If you installed GitLab from source, make sure `rsync` is installed.
+If you installed GitLab from source, make sure `rsync` is installed.
 
 ```shell
 cd /home/git/gitlab
@@ -61,7 +61,8 @@ sudo service gitlab stop
 
 ### 3. Update Ruby
 
-NOTE: Beginning in GitLab 13.6, we only support Ruby 2.7 or higher, and dropped
+NOTE:
+Beginning in GitLab 13.6, we only support Ruby 2.7 or higher, and dropped
 support for Ruby 2.6. Be sure to upgrade if necessary.
 
 You can check which version you are running with `ruby -v`.
@@ -81,7 +82,7 @@ sudo make install
 
 ### 4. Update Node.js
 
-NOTE: To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions).
+To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions).
 
 GitLab also requires the use of Yarn `>= v1.10.0` to manage JavaScript
 dependencies.
@@ -99,7 +100,7 @@ More information can be found on the [Yarn website](https://classic.yarnpkg.com/
 
 ### 5. Update Go
 
-NOTE: To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions).
+To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions).
 
 You can check which version you are running with `go version`.
 

doc/user/asciidoc.md

@@ -48,13 +48,10 @@ monospaced font:
  and lines breaks will be preserved.
 ```
 
-An admonition paragraph grabs the reader's attention:
+Admonition paragraphs grab the reader's attention:
 
-```plaintext
-NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.
-
-TIP: Lists can be indented. Leading whitespace is not significant.
-```
+- `NOTE: This is a brief reference, please read the full documentation at https://asciidoctor.org/docs/.`
+- `TIP: Lists can be indented. Leading whitespace is not significant.`
 
 ### Text Formatting
 

doc/user/group/value_stream_analytics/index.md

@@ -22,7 +22,7 @@ For information on how to contribute to the development of Value Stream Analytic
 
 Group-level Value Stream Analytics is available via **Group > Analytics > Value Stream**.
 
-Note: [Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available.
+[Project-level Value Stream Analytics](../../analytics/value_stream_analytics.md) is also available.
 
 ## Default stages
 

doc/user/markdown.md

@@ -1056,7 +1056,7 @@ are separated into their own lines:
 ```
 
 <!--
-Note: The example below uses HTML to force correct rendering on docs.gitlab.com,
+The example below uses HTML to force correct rendering on docs.gitlab.com,
 Markdown is fine in GitLab.
 -->
 

doc/user/project/integrations/webhooks.md

@@ -409,7 +409,8 @@ X-Gitlab-Event: Issue Hook
 }
 ```
 
-NOTE: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only.
+NOTE:
+`assignee` and `assignee_id` keys are deprecated and now show the first assignee only.
 
 ### Comment events
 
@@ -734,7 +735,8 @@ X-Gitlab-Event: Note Hook
 }
 ```
 
-NOTE: `assignee_id` field is deprecated and now shows the first assignee only.
+NOTE:
+`assignee_id` field is deprecated and now shows the first assignee only.
 
 #### Comment on code snippet
 

doc/user/usage_quotas.md

@@ -40,7 +40,7 @@ storage item. Click on each project's title to see a breakdown per storage item.
 > - It's enabled on GitLab.com.
 > - It's recommended for production use.
 
-CAUTION: **Warning:**
+WARNING:
 This feature might not be available to you. Check the **version history** note above for details.
 
 The following storage usage statistics are available to an owner: