12 files changed, 55 insertions, 18 deletions
diff --git a/doc/.vale/gitlab/Admin.yml b/doc/.vale/gitlab/Admin.yml
index f6b0a988499..78a86e27456 100644
--- a/doc/.vale/gitlab/Admin.yml
+++ b/doc/.vale/gitlab/Admin.yml
@@ -1,5 +1,5 @@
 ---
-# Warning: gitlab.Admin
+# Suggestion: gitlab.Admin
 #
 # Checks for "admin" and recommends using the full word instead. "Admin Area" is OK.
 #
diff --git a/doc/.vale/gitlab/BadPlurals.yml b/doc/.vale/gitlab/BadPlurals.yml
index 63f002fec94..533805c67b0 100644
--- a/doc/.vale/gitlab/BadPlurals.yml
+++ b/doc/.vale/gitlab/BadPlurals.yml
@@ -1,5 +1,5 @@
 ---
-# Suggestion: gitlab.BadPlurals
+# Warning: gitlab.BadPlurals
 #
 # Don't write plural words with the '(s)' construction. "HTTP(S)" is acceptable.
 #
diff --git a/doc/.vale/gitlab/EOLWhitespace.yml b/doc/.vale/gitlab/EOLWhitespace.yml
index 483db0cafe6..e160b706014 100644
--- a/doc/.vale/gitlab/EOLWhitespace.yml
+++ b/doc/.vale/gitlab/EOLWhitespace.yml
@@ -1,5 +1,5 @@
 ---
-# Error: gitlab.EOLWhitespace
+# Warning: gitlab.EOLWhitespace
 #
 # Checks that there is no useless whitespace at the end of lines.
 #
diff --git a/doc/.vale/gitlab/FutureTense.yml b/doc/.vale/gitlab/FutureTense.yml
index fc414a9c0fd..64e79612fff 100644
--- a/doc/.vale/gitlab/FutureTense.yml
+++ b/doc/.vale/gitlab/FutureTense.yml
@@ -1,5 +1,5 @@
 ---
-# Suggestion: gitlab.FutureTense
+# Warning: gitlab.FutureTense
 #
 # Checks for use of future tense in sentences. Present tense is strongly preferred.
 #
diff --git a/doc/.vale/gitlab/HeadingContent.yml b/doc/.vale/gitlab/HeadingContent.yml
index a8dc596f2a2..c2dd2a5c6c2 100644
--- a/doc/.vale/gitlab/HeadingContent.yml
+++ b/doc/.vale/gitlab/HeadingContent.yml
@@ -1,5 +1,5 @@
 ---
-# Error: gitlab.HeadingContent
+# Warning: gitlab.HeadingContent
 #
 # Checks for generic, unhelpful subheadings.
 #
diff --git a/doc/.vale/gitlab/HeadingDepth.yml b/doc/.vale/gitlab/HeadingDepth.yml
new file mode 100644
index 00000000000..466ab317226
--- /dev/null
+++ b/doc/.vale/gitlab/HeadingDepth.yml
@@ -0,0 +1,13 @@
+---
+# Warning: gitlab.HeadingDepth
+#
+# Checks that there are no headings greater than 3 levels
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: 'The subheading "%s" is nested too deeply. Headings deeper than H5 suggest the section or page should be refactored.'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#headings-in-markdown
+level: warning
+scope: raw
+raw:
+  - '(?<=\n)#{5,}\s.*'
diff --git a/doc/.vale/gitlab/MultiLineLinks.yml b/doc/.vale/gitlab/MultiLineLinks.yml
new file mode 100644
index 00000000000..64ad017f16c
--- /dev/null
+++ b/doc/.vale/gitlab/MultiLineLinks.yml
@@ -0,0 +1,14 @@
+---
+# Error: gitlab.MultiLineLinks
+#
+# Checks that links are all on a single line.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: 'Link "%s" must be on a single line, even if very long.'
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#basic-link-criteria
+level: error
+scope: raw
+raw:
+  - '\[[^\[\]]*?\n[^\[\]]*?\]\([^\)]*?\)|'
+  - '\[[^\[\]]*?\]\([^\)]*?\n[^\)]*\)'
diff --git a/doc/.vale/gitlab/OutdatedVersions.yml b/doc/.vale/gitlab/OutdatedVersions.yml
index c78c045a1fd..f25de44ad17 100644
--- a/doc/.vale/gitlab/OutdatedVersions.yml
+++ b/doc/.vale/gitlab/OutdatedVersions.yml
@@ -1,5 +1,5 @@
 ---
-# Warning: gitlab.OutdatedVersions
+# Suggestion: gitlab.OutdatedVersions
 #
 # Checks for references to versions of GitLab that are no longer supported.
 #
diff --git a/doc/.vale/gitlab/Possessive.yml b/doc/.vale/gitlab/Possessive.yml
index 158c689cac1..92ae66543a2 100644
--- a/doc/.vale/gitlab/Possessive.yml
+++ b/doc/.vale/gitlab/Possessive.yml
@@ -1,5 +1,5 @@
 ---
-# Warning: gitlab.Possessive
+# Error: gitlab.Possessive
 #
 # The word GitLab should not be used in the possessive form.
 #
diff --git a/doc/.vale/gitlab/Uppercase.yml b/doc/.vale/gitlab/Uppercase.yml
index a8519d898db..dc05aa05730 100644
--- a/doc/.vale/gitlab/Uppercase.yml
+++ b/doc/.vale/gitlab/Uppercase.yml
@@ -56,6 +56,7 @@ exceptions:
   - DML
   - DNS
   - DOM
+  - DORA
   - DSA
   - DSL
   - DVCS
diff --git a/doc/.vale/gitlab/VersionText.yml b/doc/.vale/gitlab/VersionText.yml
index 68753de60aa..571fba52ab7 100644
--- a/doc/.vale/gitlab/VersionText.yml
+++ b/doc/.vale/gitlab/VersionText.yml
@@ -1,23 +1,19 @@
 ---
 # Error: gitlab.VersionText
 #
-# Checks that version text is formatted correctly.
+# Checks that multi-line version text is formatted correctly.
 #
-# Specifically looks for either of the following that is immediately followed on the next line
-# by content, which will break rendering:
+# Specifically, looks for multi-line version text that doesn't use `-` to make it a list.
+# For example:
 #
-# - `> Introduced` (version text without a link)
-# - `> [Introduced` (version text with a link)
-#
-# Because it excludes the prefix `> - `, it doesn't look for multi-line version text, for which
-# content immediately on the next line is ok. However, this will often highlight where multi-line
-# version text is attempted without `-` characters.
+# - `> Introduced in GitLab 14.0.
+# - `> Removed in GitLab 15.0.
 #
 # For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
 extends: existence
-message: 'This introduced-in line is not formatted correctly.'
+message: 'This introduced-in section is not formatted correctly. Each entry must start with `> -` and long entries must be on one line.'
 link: https://docs.gitlab.com/ee/development/documentation/versions.html
 level: error
 scope: raw
 raw:
-  - '> \[?Introduced.+\n[^\n]'
+  - '\n#.*\n\n> [^-].+\n[^\n`]'
diff --git a/doc/.vale/gitlab/VersionTextSingleLine.yml b/doc/.vale/gitlab/VersionTextSingleLine.yml
new file mode 100644
index 00000000000..f76574bcf8a
--- /dev/null
+++ b/doc/.vale/gitlab/VersionTextSingleLine.yml
@@ -0,0 +1,13 @@
+---
+# Error: gitlab.VersionTextSingleLine
+#
+# Verifies that single-item version notes don't have a hyphen.
+#
+# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+extends: existence
+message: 'Version text with only a single item must not start with a hyphen.'
+link: https://docs.gitlab.com/ee/development/documentation/versions.html#add-a-version-history-item
+level: error
+scope: raw
+raw:
+  - '(\r|\n|\r\n){2}(> - .*)(\r|\n|\r\n){2}'