chore: update Vale and Markdownlint versions and configuration

.gitlab-ci.yml

@@ -63,7 +63,7 @@ check_docs_update:
         fi
 
 check_docs_markdown:
-  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.16-vale-2.20.1-markdownlint-0.32.2
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.18-vale-2.29.6-markdownlint-0.37.0-markdownlint2-0.10.0
   extends: .documentation
   script:
     # Lint prose

.markdownlint.yml

@@ -33,7 +33,6 @@ proper-names:
     "API",
     "Asana",
     "Auth0",
-    "Authentiq",
     "Azure",
     "Bamboo",
     "Bitbucket",
@@ -53,10 +52,12 @@ proper-names:
     "Geo",
     "Git LFS",
     "git-annex",
-    "git-credential",
+    "git-credential-oauth",
     "git-sizer",
+    "Git",
     "Gitaly",
     "GitHub",
+    "gitlab.vim",
     "GitLab Geo",
     "GitLab Monitor",
     "GitLab Operator",
@@ -98,17 +99,18 @@ proper-names:
     "minikube",
     "MinIO",
     "ModSecurity",
+    "Neovim",
     "NGINX Ingress",
     "NGINX",
     "OAuth",
     "OAuth 2",
     "OmniAuth",
-    "Omnibus GitLab",
     "OpenID",
     "OpenShift",
     "PgBouncer",
     "Postfix",
     "PostgreSQL",
+    "PowerShell",
     "Praefect",
     "Prometheus",
     "Puma",
@@ -130,7 +132,6 @@ proper-names:
     "Slack",
     "SMTP",
     "SpotBugs",
-    "ssh-key",
     "SSH",
     "Tiller",
     "TOML",
@@ -150,3 +151,4 @@ proper-names:
     "YouTrack"
   ]
   code_blocks: false
+  html_elements: false

.tool-versions

@@ -1 +1,2 @@
 golang 1.19.13
+vale 2.29.6

CONTRIBUTING.md

@@ -199,7 +199,7 @@ This is a very short description of the change
 
 Just as in the description, use imperative, present tense: “change” not “changed” nor “changes.” Include motivation for the change and contrast it with previous behavior.
 
-#### More info on writing good git commit messages
+#### More info on writing good Git commit messages
 
 - [Writing Git commit messages](http://365git.tumblr.com/post/3308646748/writing-git-commit-messages)
 - [A Note About Git Commit Messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html)

README.md

@@ -80,7 +80,7 @@ Many core commands also have sub-commands. Some examples:
 
 ## Documentation
 
-Read the [documentation](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source) for usage instructions or check out `glab help`.
+Read the [documentation](docs/source/index.md) for usage instructions or check out `glab help`.
 
 ## Installation
 
@@ -189,8 +189,8 @@ the `GITLAB_HOST` environment variable, like this:
 - `GITLAB_HOST=gitlab.example.com glab repo clone group/project`
 - `GITLAB_HOST=gitlab.example.com glab issue list -R group/project`
 
-When inside a git repository `glab` will use that repository's GitLab host by default. For example `glab issue list`
-will list all issues of the current directory's git repository.
+When inside a Git repository `glab` will use that repository's GitLab host by default. For example `glab issue list`
+will list all issues of the current directory's Git repository.
 
 ### Configure `glab` to use self-signed certificates for self-managed instances
 

cmd/gen-docs/docs.go

@@ -137,9 +137,9 @@ func printSubcommands(cmd *cobra.Command, buf *bytes.Buffer) {
 	for _, cmdC := range cmd.Commands() {
 		if cmdC.Name() != "help" {
 			if cmdC.HasAvailableSubCommands() {
-				subcommands += fmt.Sprintf("- [%s](%s/index.md)\n", cmdC.Name(), cmdC.Name())
+				subcommands += fmt.Sprintf("- [`%s`](%s/index.md)\n", cmdC.Name(), cmdC.Name())
 			} else {
-				subcommands += fmt.Sprintf("- [%s](%s.md)\n", cmdC.Name(), cmdC.Name())
+				subcommands += fmt.Sprintf("- [`%s`](%s.md)\n", cmdC.Name(), cmdC.Name())
 			}
 		}
 	}

commands/completion/completion.go

@@ -102,7 +102,7 @@ func NewCmdCompletion(io *iostreams.IOStreams) *cobra.Command {
 		%[2]s
 
 		To load completions for every new session, add the output of the above command
-		to your powershell profile.
+		to your PowerShell profile.
 
 		When installing glab through a package manager, however, it's possible that
 		no additional shell configuration is necessary to gain completion support.

docs/.vale/gitlab/Admin.yml

@@ -1,13 +0,0 @@
----
-# Suggestion: gitlab.Admin
-#
-# Checks for "admin" and recommends using the full word instead. "Admin Area" is OK.
-#
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: substitution
-message: 'Verify this use of the word "admin". Can it be updated to "administration", "administrator", "administer", or "Admin Area"?'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html
-level: suggestion
-ignorecase: false
-swap:
-  '[Aa]dmin ?\w*': '(?:Admin( Area| Mode)?|[Aa]dminist(ration|rator|rators|er|rative|ering|ered))'

docs/.vale/gitlab/AlertBoxStyle.yml

@@ -3,13 +3,13 @@
 #
 # Makes sure alert boxes are used with block quotes. Checks for 3 formatting issues:
 #
-# - Alert boxes inside a block quote (">")
+# - 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"
+# - 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
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Alert box "%s" must use the formatting in the style guide.'
+message: "Update the format of the '%s' alert box. View the style guide for details."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#alert-boxes
 level: error
 nonword: true

docs/.vale/gitlab/BadPlurals.yml

@@ -1,11 +1,11 @@
 ---
 # Warning: gitlab.BadPlurals
 #
-# Don't write plural words with the '(s)' construction. "HTTP(S)" is acceptable.
+# Don't write plural words with the '(s)' construction. 'HTTP(S)' is acceptable.
 #
-# For a list of all options, see https://docs.errata.ai/vale/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Rewrite "%s" to be plural, without parentheses.'
+message: "Rewrite '%s' to be plural without parentheses."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#s
 level: warning
 ignorecase: true

docs/.vale/gitlab/BadgeCapitalization.yml

@@ -3,12 +3,12 @@
 #
 # Verifies that badges are not mixed case, which won't render properly.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Badge "%s" must be capitalized.'
+message: "Capitalize the '%s' badge."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#product-tier-badges
 level: error
 scope: raw
 raw:
-  - '(?!\*\*\((FREE|PREMIUM|ULTIMATE)( (SELF|SAAS))?\)\*\*)'
-  - '(?i)\*\*\((free|premium|ultimate)( (self|saas))?\)\*\*'
+  - '(?!\*\*\((FREE|PREMIUM|ULTIMATE)( (SELF|SAAS|ALL) (BETA|EXPERIMENT))?\)\*\*)'
+  - '(?i)\*\*\((free|premium|ultimate)( (self|saas|all) (beta|experiment))?\)\*\*'

docs/.vale/gitlab/British.yml

@@ -3,9 +3,9 @@
 #
 # Checks that US spelling is used instead of British spelling.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use the US spelling "%s" instead of the British "%s".'
+message: "Use the US spelling '%s' instead of the British '%s'."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
 level: error
 ignorecase: true

docs/.vale/gitlab/CIConfigFile.yml

@@ -3,15 +3,11 @@
 #
 # Checks that the `.gitlab-ci.yml` file is referenced properly.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'The CI/CD configuration file should be exactly: `.gitlab-ci.yml`'
+message: "Change the file name to be exactly '.gitlab-ci.yml'."
 link: https://docs.gitlab.com/ee/development/documentation/versions.html
 level: error
 scope: raw
 raw:
-  - '(`gitlab-ci.yml`|'
-  - '`gitlabci.yml`|'
-  - '`gitlab.ci.yml`|'
-  - '`.gitlab.ci-yml`|'
-  - '`.gitlab-ci.yaml`)'
+  - '(?!`\.gitlab-ci\.yml`)`.?gitlab.?ci.?ya?ml`'

docs/.vale/gitlab/CodeblockFences.yml

@@ -3,11 +3,11 @@
 #
 # Ensures all codeblock language tags use the full name, not aliases.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Syntax highlighting hint "%s" must be one of: yaml, ruby, plaintext, markdown, javascript, shell, golang, python, dockerfile, or typescript.'
+message: "Instead of '%s' for the code block, use yaml, ruby, plaintext, markdown, javascript, shell, go, python, dockerfile, or typescript."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#code-blocks
 level: error
 scope: raw
 raw:
-  - '\`\`\`(yml|rb|text|md|bash|sh\n|js\n|go\n|py\n|docker\n|ts)'
+  - '\`\`\`(yml|rb|text|md|bash|sh\n|js\n|golang\n|py\n|docker\n|ts)'

docs/.vale/gitlab/CommandStringsQuoted.yml

@@ -0,0 +1,14 @@
+---
+# Error: gitlab.CommandStringsQuoted
+#
+# Ensures all code blocks wrap URL strings in quotation marks.
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "For the command example, use double quotes around the URL: %s"
+link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands
+level: error
+scope: raw
+nonword: true
+tokens:
+  - '(curl|--url)[^"\]\n]+?https?:\/\/[^ \n]*'

docs/.vale/gitlab/CurlStringsQuoted.yml

@@ -1,13 +0,0 @@
----
-# Error: gitlab.CurlStringsQuoted
-#
-# Ensures all code blocks using `curl` wrap URL strings in quotation marks.
-#
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: existence
-message: 'For consistency across all cURL examples, always wrap the URL in double quotes ("): %s'
-link: https://docs.gitlab.com/ee/development/documentation/restful_api_styleguide.html#curl-commands
-level: error
-scope: code
-raw:
-  - 'curl [^"]+://.*'

docs/.vale/gitlab/CurrentStatus.yml

@@ -1,14 +1,13 @@
 ---
-# Suggestion: gitlab.CurrentStatus
+# Warning: gitlab.CurrentStatus
 #
 # Checks for words that indicate a product or feature may change in the future.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Avoid words like "%s" when you write about future features. Our documentation is about the current state of the product.'
-level: suggestion
+message: "Remove '%s'. The documentation reflects the current state of the product."
+level: warning
 ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/#promising-features-in-future-versions
+link: https://docs.gitlab.com/ee/development/documentation/versions.html#promising-features-in-future-versions
 tokens:
   - currently
-  - yet

docs/.vale/gitlab/DefaultBranch.yml

@@ -1,14 +1,14 @@
 ---
 # Warning: gitlab.DefaultBranch
 #
-# Do not refer to the default branch as the "master" branch, if possible.
+# Do not refer to the default branch as the 'master' branch, if possible.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Use "default branch" or `main` instead of `master`, when possible.'
+message: "Use 'default branch' or `main` instead of `master`, when possible."
 level: warning
 ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#default-branch
 scope: raw
 raw:
   - '\`master\`'

docs/.vale/gitlab/Dropdown.yml

@@ -3,11 +3,11 @@
 #
 # Catches many ways the phrase 'dropdown list' can be fumbled.
 #
-# For a list of all options, see https://errata-ai.github.io/vale/styles/
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Use "dropdown list".'
+message: "Use 'dropdown list'."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#dropdown-list
-level: suggestion
+level: warning
 ignorecase: true
 tokens:
   - drop-down( [\w]*)?

docs/.vale/gitlab/EOLWhitespace.yml

@@ -3,9 +3,9 @@
 #
 # Checks that there is no useless whitespace at the end of lines.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Lines should not end with whitespace characters.'
+message: "Remove whitespace characters from the end of the line."
 link: https://docs.gitlab.com/ee/development/documentation/versions.html
 level: warning
 scope: raw

docs/.vale/gitlab/ElementDescriptors.yml

@@ -1,13 +1,14 @@
 ---
-# Suggestion: gitlab.ElementDescriptors
+# Warning: gitlab.ElementDescriptors
 #
-# Suggests the correct way to describe elements in a form.
+# Suggests the correct way to describe a button.
 #
-# For a list of all options, see https://errata-ai.github.io/vale/styles/
-extends: substitution
-message: 'When describing elements, %s "%s".'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
-level: suggestion
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "If possible, rewrite to remove 'button'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#button
+level: warning
 ignorecase: true
-swap:
-  button: 'if possible, rewrite to remove'
+scope: raw
+raw:
+  - \*\*[^*]+\*\*\s+button

docs/.vale/gitlab/FirstPerson.yml

@@ -1,16 +0,0 @@
----
-# Warning: gitlab.FirstPerson
-#
-# Checks for use of first person pronouns.
-#
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: existence
-message: '"%s" is a first-person pronoun. Use second- or third-person pronouns (like we, you, us, one) instead.'
-level: warning
-ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
-tokens:
-  - '\bI[ ,;:?!"]|\bI\x27.{1,2}'
-  - me
-  - myself
-  - mine

docs/.vale/gitlab/FutureTense.yml

@@ -3,12 +3,12 @@
 #
 # Checks for use of future tense in sentences. Present tense is strongly preferred.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Avoid using future tense: "%s". Use present tense instead.'
+message: "Instead of future tense '%s', use present tense."
 ignorecase: true
 level: warning
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#future-tense
 raw:
   - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
   - "will( |\n|[[:punct:]])[a-zA-Z]*|"

docs/.vale/gitlab/GitLabFlavoredMarkdown.yml

@@ -0,0 +1,14 @@
+---
+# Warning: gitlab.GitLabFlavoredMarkdown
+#
+# Checks for unclear use of GLFM or GLM instead of GitLab/GitHub Flavored Markdown
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: substitution
+message: "Use '%s' instead of '%s' when possible."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
+level: warning
+ignorecase: true
+swap:
+  GLFM: "GitLab Flavored Markdown"
+  GFM: "GitLab Flavored Markdown' or 'GitHub Flavored Markdown"

docs/.vale/gitlab/HeadingContent.yml

@@ -3,16 +3,17 @@
 #
 # Checks for generic, unhelpful subheadings.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Rename the subheading "%s", or re-purpose the content elsewhere.'
+message: "Rename the heading '%s', or re-purpose the content elsewhere."
 level: warning
-scope: heading
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/#headings-1
-ignorecase: false
+link: https://docs.gitlab.com/ee/development/documentation/topic_types/concept.html#concept-headings
+ignorecase: true
+nonword: true
+scope: raw
 tokens:
-  - How it works
-  - Limitations
-  - Overview
-  - Use cases?
-  - Important notes?
+  - '\#+ How it works'
+  - '\#+ Limitations'
+  - '\#+ Overview'
+  - '\#+ Use cases?'
+  - '\#+ Important notes?'

docs/.vale/gitlab/HeadingDepth.yml

@@ -1,13 +1,13 @@
 ---
-# Warning: gitlab.HeadingDepth
+# Suggestion: 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
+message: "Refactor the section or page to avoid headings greater than H5."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#heading-levels-in-markdown
+level: suggestion
 scope: raw
 raw:
-  - '(?<=\n)#{5,}\s.*'
+  - '(?<=\n)#{6,}\s.*'

docs/.vale/gitlab/InclusionAbleism.yml

@@ -1,13 +1,13 @@
 ---
-# Suggestion: gitlab.InclusionAbleism
+# Warning: gitlab.InclusionAbleism
 #
 # Suggests alternatives for words that foster ableism.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use inclusive language. Consider "%s" instead of "%s".'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language
-level: suggestion
+message: "Use inclusive language. Consider '%s' instead of '%s'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
+level: warning
 ignorecase: true
 swap:
   sanity (?:check|test): check for completeness

docs/.vale/gitlab/InclusionCultural.yml

@@ -3,10 +3,10 @@
 #
 # Suggests alternatives for words that are culturally inappropriate.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use inclusive language. Consider "%s" instead of "%s".'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language
+message: "Use inclusive language. Consider '%s' instead of '%s'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 level: warning
 ignorecase: true
 swap:

docs/.vale/gitlab/InclusionGender.yml

@@ -1,13 +1,13 @@
 ---
-# Suggestion: gitlab.InclusionGender
+# Warning: gitlab.InclusionGender
 #
 # Suggests alternatives for words that are gender-specific.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use inclusive language. Consider "%s" instead of "%s".'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#inclusive-language
-level: suggestion
+message: "Use inclusive language. Consider '%s' instead of '%s'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
+level: warning
 ignorecase: true
 swap:
   mankind: humanity, people

docs/.vale/gitlab/InternalLinkCase.yml

@@ -3,10 +3,10 @@
 #
 # Checks that anchor fragments on internal links are in lower-case.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Links to subheadings in GitLab docs must be in lower-case: "%s"'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
+message: "Use lowercase for the anchor link."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#anchor-links
 level: error
 scope: raw
 raw:

docs/.vale/gitlab/InternalLinkExtension.yml

@@ -3,10 +3,10 @@
 #
 # Checks that internal links have .md extenstion and not .html extension.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Link "%s" must link directly to a file and use the .md file extension.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
+message: "Link to a file and use the .md file extension instead of .html."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
 level: error
 scope: raw
 raw:

docs/.vale/gitlab/InternalLinkFormat.yml

@@ -1,13 +1,13 @@
 ---
 # Error: gitlab.InternalLinkFormat
 #
-# Checks that internal link paths don't start with "./", which is not needed.
+# Checks that internal link paths don't start with './', which is not needed.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Link "%s" must not start with "./".'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
+message: "Edit the link so it does not start with './'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
 level: error
 scope: raw
 raw:
-  - '\[.+\]\(\.\/.*?\)'
+  - '\[[^\]]+\]\(\.\/.*?\)'

docs/.vale/gitlab/LatinTerms.yml

@@ -3,10 +3,10 @@
 #
 # Checks for use of Latin terms.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use "%s" instead of "%s", but consider rewriting the sentence.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
+message: "Use '%s' instead of '%s', but consider rewriting the sentence."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 level: warning
 nonword: true
 ignorecase: true
@@ -15,3 +15,4 @@ swap:
   e\. g\.: for example
   i\.e\.: that is
   i\. e\.: that is
+  via: "Use 'with', 'through', or 'by using' instead."

docs/.vale/gitlab/Markdown_emoji.yml

@@ -1,13 +0,0 @@
----
-# Warning: gitlab.Markdown_emoji
-#
-# Check for use of GLFM emoji syntax (https://docs.gitlab.com/ee/user/markdown.html#emojis), which doesn't render correctly in documentation.
-#
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
-extends: existence
-message: 'This appears to be GLFM emoji syntax. Replace "%s" with GitLab SVGs or Unicode emojis.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/#gitlab-svg-icons
-level: warning
-scope: text
-raw:
-  - '(?:\s+|^):[a-zA-Z0-9\-_\+]+:(?:\s+|$|\.)'

docs/.vale/gitlab/MeaningfulLinkWords.yml

@@ -3,13 +3,14 @@
 #
 # Checks for the presence of semantically unhelpful words in link text.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Improve SEO and accessibility by rewriting "%s" in the link text.'
+message: "Improve SEO and accessibility by rewriting the link text for '%s'."
 level: warning
-scope: link
 ignorecase: true
-link: https://about.gitlab.com/handbook/communication/#writing-style-guidelines
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#text-for-links
+scope: raw
+nonword: true
 tokens:
-  - here
-  - this page
+  - \[here\]\(.*\)
+  - \[this page\]\(.*\)

docs/.vale/gitlab/MergeConflictMarkers.yml

@@ -3,9 +3,9 @@
 #
 # Checks for the presence of merge conflict markers.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Merge conflict marker "%s" found.'
+message: "Remove the merge conflict marker '%s'."
 link: https://docs.gitlab.com/ee/development/code_review.html#merging-a-merge-request
 level: error
 scope: raw

docs/.vale/gitlab/MultiLineLinks.yml

@@ -3,10 +3,10 @@
 #
 # 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
+# For a list of all options, see https://vale.sh/docs/topics/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
+message: "Put the full link on one line, even if the link is very long."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
 level: error
 scope: raw
 raw:

docs/.vale/gitlab/NonStandardQuotes.yml

@@ -3,12 +3,12 @@
 #
 # Use only standard single and double quotes, not left or right quotes.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Use standard single quotes or double quotes only. Do not use left or right quotes.'
+message: "Use standard single quotes or double quotes only. Do not use left or right quotes."
 level: warning
 ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation
 scope: raw
 raw:
   - '[‘’“”]'

docs/.vale/gitlab/Normal.yml

@@ -0,0 +1,14 @@
+---
+# Warning: gitlab.Normal
+#
+# Suggests alternatives for 'normal'.
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: substitution
+message: "Use '%s' instead of '%s'."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
+level: warning
+ignorecase: true
+swap:
+  normally: "usually' or 'typically"
+  normal:  "typical' or 'standard"

docs/.vale/gitlab/OutdatedVersions.yml

@@ -3,10 +3,10 @@
 #
 # Checks for references to versions of GitLab that are no longer supported.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Can this reference to "%s" be refactored?'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#gitlab-versions
+message: "If possible, remove the reference to '%s'."
+link: https://docs.gitlab.com/ee/development/documentation/versions.html
 level: suggestion
 nonword: true
 ignorecase: true
@@ -22,3 +22,4 @@ tokens:
   - "GitLab (v)?10."
   - "GitLab (v)?11."
   - "GitLab (v)?12."
+  - "GitLab (v)?13."

docs/.vale/gitlab/OxfordComma.yml

@@ -3,9 +3,9 @@
 #
 # Checks for the lack of an Oxford comma. In some cases, will catch overly complex sentence structures with lots of commas.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Use a comma before the last "and" or "or" in a list of four or more items.'
+message: "Use a comma before the last 'and' or 'or' in a list of four or more items."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation
 level: warning
 raw:

docs/.vale/gitlab/Possessive.yml

@@ -3,11 +3,11 @@
 #
 # The word GitLab should not be used in the possessive form.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: "Rewrite '%s' to not use 's."
+message: "Remove 's from %s."
 level: error
 ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#trademark
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab
 tokens:
   - GitLab's

docs/.vale/gitlab/Prerequisites.yml

@@ -0,0 +1,14 @@
+---
+# Error: gitlab.Prerequisites
+#
+# The "Prerequisites:" line should always be plural.
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "Pluralize 'Prerequisites', even if it includes only one item."
+link: https://docs.gitlab.com/ee/development/documentation/topic_types/task.html#task-prerequisites
+level: warning
+nonword: true
+scope: text
+raw:
+  - '^Prerequisite:'

docs/.vale/gitlab/ReadingLevel.yml

@@ -4,8 +4,10 @@
 # Checks the Flesch-Kincaid reading level.
 #
 # https://docs.errata.ai/vale/styles#metric
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: metric
-message: "The grade level - %s - refers to how hard the content is to understand. Aim for 8th grade or lower by using shorter sentences and words."
+message: "The grade level is %s. Aim for 8th grade or lower by using shorter sentences and words."
 link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-readability-score
 level: suggestion
 formula: |

docs/.vale/gitlab/ReferenceLinks.yml

@@ -3,10 +3,10 @@
 #
 # Checks for reference-style links that should be converted to inline links.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Link "%s" must be inline.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#basic-link-criteria
+message: "Put this link inline with the rest of the text."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
 level: error
 scope: raw
 raw:

docs/.vale/gitlab/RelativeLinks.yml

@@ -3,11 +3,11 @@
 #
 # Checks for the presence of absolute hyperlinks that should be relative.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Link "%s" must be a relative link with a .md extension.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
-level: warning
+message: "Use a relative link instead of a URL, and ensure the file name ends in .md and not .html."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
+level: error
 scope: raw
 raw:
-  - '\[.+\]\(https?:\/\/docs\.gitlab\.com\/[ce]e.*\)'
+  - '\[[^\]]+\]\(https://gitlab.com/gitlab-org/cli/-/tree/main/docs.*\)'

docs/.vale/gitlab/RelativeLinksDoubleSlashes.yml

@@ -3,10 +3,10 @@
 #
 # Checks for the presence of double slashes in relative URLs.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Relative links must not include a double slash.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links-to-internal-documentation
+message: "Remove the double slash from this relative link."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#links
 level: error
 scope: raw
 raw:

docs/.vale/gitlab/Repetition.yml

@@ -3,9 +3,9 @@
 #
 # Checks for duplicate words, like `the the` or `and and`.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: repetition
-message: '"%s" is repeated.'
+message: "Remove this duplicate word: '%s'."
 level: error
 alpha: true
 tokens:

docs/.vale/gitlab/SentenceLength.yml

@@ -1,13 +1,13 @@
 ---
-# Warning: gitlab.SentenceLength
+# Suggestion: gitlab.SentenceLength
 #
 # Counts words in a sentence and alerts if a sentence exceeds 25 words.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: occurrence
-message: 'Shorter sentences improve readability (max 25 words).'
+message: "Improve readability by using fewer than 25 words in this sentence."
 scope: sentence
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#language
-level: warning
+level: suggestion
 max: 25
 token: \b(\w+)\b

docs/.vale/gitlab/SentenceSpacing.yml

@@ -3,9 +3,9 @@
 #
 # Checks for incorrect spacing (no spaces, or more than one space) around punctuation.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: '"%s" must contain one and only one space.'
+message: "Remove the extra space: '%s'"
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#punctuation
 level: error
 nonword: true

docs/.vale/gitlab/Simplicity.yml

@@ -1,14 +1,14 @@
 ---
-# Suggestion: gitlab.Simplicity
+# Warning: gitlab.Simplicity
 #
 # Checks for words implying ease of use, to avoid cognitive dissonance for frustrated users.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Avoid words like "%s" that imply ease of use, because the user may find this action hard.'
-level: suggestion
+message: "Remove '%s'. Be precise instead of subjective."
+level: warning
 ignorecase: true
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#usage-list
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 tokens:
   - easy
   - easily

docs/.vale/gitlab/Spelling.yml

@@ -8,9 +8,9 @@
 # Commands, like `git clone` must use backticks, and must not be added to the
 # exceptions.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: spelling
-message: 'Spelling check: "%s"?'
+message: "Check the spelling of '%s'. If the spelling is correct, ask a Technical Writer to add this word to the spelling exception list."
 level: warning
 ignore:
   - gitlab/spelling-exceptions.txt

docs/.vale/gitlab/SubstitutionSuggestions.yml

@@ -1,28 +0,0 @@
----
-# Suggestion: gitlab.SubstitutionSuggestions
-#
-# Suggests better options for frequently misused terms that are often - but not always - incorrect.
-# SubstitutionWarning.yml and Substitutions.yml also exist.
-#
-# For a list of all options, see https://errata-ai.github.io/vale/styles/
-extends: substitution
-message: 'Consider %s instead of "%s".'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
-level: suggestion
-ignorecase: true
-swap:
-  active user: '"billable user"'
-  active users: '"billable users"'
-  docs: '"documentation"'
-  e-mail: '"email"'
-  GLFM: '"GitLab Flavored Markdown"'
-  it is recommended: '"we recommend"'
-  navigate: go
-  OAuth2: '"OAuth 2.0"'
-  once that: '"after that"'
-  once the: '"after the"'
-  once you: '"after you"'
-  since: '"because" or "after"'
-  sub-group: '"subgroup"'
-  sub-groups: '"subgroups"'
-  within: '"in"'

docs/.vale/gitlab/SubstitutionWarning.yml

@@ -1,29 +1,66 @@
 ---
 # Warning: gitlab.SubstitutionWarning
 #
-# Checks for misused terms or common shorthand that should never be used at GitLab, but can't be flagged as errors.
-# Substitutions.yml and SubstitionSuggestions.yml also exist.
+# Checks for misused terms or common shorthand that should not be used at GitLab, but can't be flagged as errors.
+# Substitutions.yml also exists.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'If possible, use "%s" instead of "%s".'
-link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+message: "Use '%s' instead of '%s' when possible."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 level: warning
 ignorecase: true
 swap:
-  air(?:-| )?gapped: offline environment
-  bullet: list item
-  click: select
-  code base: codebase
-  config: configuration
-  deselect: clear
-  deselected: cleared
-  distro: distribution
-  file name: filename
-  filesystem: file system
-  GFM: GLFM
-  info: information
-  n/a: not applicable
-  repo: repository
-  timezone: time zone
-  utilize: use
+  active user: "billable user"
+  active users: "billable users"
+  air(?:-| )?gapped: "offline environment"
+  bullet: "list item"
+  click: "select"
+  code base: "codebase"
+  config: "configuration"
+  confirmation box: "confirmation dialog"
+  confirmation dialog box: "confirmation dialog"
+  deselect: "clear"
+  deselected: "cleared"
+  dialog box: "dialog"
+  distro: "distribution"
+  docs: "documentation"
+  e-mail: "email"
+  emojis: "emoji"
+  ex: "for example"
+  file name: "filename"
+  filesystem: "file system"
+  info: "information"
+  installation from source: self-compiled installation
+  installations from source: self-compiled installations
+  it is recommended: "you should"
+  logged in user: "authenticated user"
+  logged-in user: "authenticated user"
+  modal dialog: "dialog"
+  modal window: "dialog"
+  modal: "dialog"
+  n/a: "not applicable"
+  navigate to: "go to"
+  OAuth2: "OAuth 2.0"
+  omnibus gitlab: "Linux package"
+  'omnibus(?!\))': "Linux package"
+  once that: "after that"
+  once the: "after the"
+  once you: "after you"
+  pack file: packfile
+  pack files: packfiles
+  pop-up window: "dialog"
+  pop-up: "dialog"
+  popup: "dialog"
+  repo: "repository"
+  signed in user: "authenticated user"
+  signed-in user: "authenticated user"
+  since: "because' or 'after"
+  source (?:install|installation): self-compiled installation
+  source (?:installs|installations): self-compiled installations
+  sub-group: "subgroup"
+  sub-groups: "subgroups"
+  timezone: "time zone"
+  utiliz(?:es?|ing): "use"
+  we recommend: "you should"
+  within: "in"

docs/.vale/gitlab/Substitutions.yml

@@ -2,11 +2,11 @@
 # Error: gitlab.Substitutions
 #
 # Checks for misused terms that should never be used at GitLab.
-# SubstitutionWarning.yml and SubstitionSuggestions.yml also exist.
+# SubstitutionWarning.yml also exists.
 #
-# For a list of all options, see https://docs.errata.ai/vale/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use "%s" instead of "%s".'
+message: "Use '%s' instead of '%s'."
 link: https://about.gitlab.com/handbook/communication/#top-misused-terms
 level: error
 ignorecase: true
@@ -14,15 +14,17 @@ swap:
   codequality: code quality
   Customer [Pp]ortal: Customers Portal
   disallow: prevent
+  '(?<!GitLab )Duo': GitLab Duo
   frontmatter: front matter
   GitLabber: GitLab team member
   GitLabbers: GitLab team members
   GitLab-shell: GitLab Shell
-  gitlab omnibus: Omnibus GitLab
+  gitlab omnibus: Linux package
   param: parameter
   params: parameters
   pg: PostgreSQL
   'postgres$': PostgreSQL
+  golang: Go
   raketask: Rake task
   raketasks: Rake tasks
   rspec: RSpec
@@ -60,3 +62,4 @@ swap:
   reporter access: the Reporter role
   reporter permission: the Reporter role
   reporter permissions: the Reporter role
+  at least the Owner role: the Owner role

docs/.vale/gitlab/TabsLinks.yml

@@ -0,0 +1,13 @@
+---
+# Error: gitlab.TabsLinks
+#
+# Checks for the presence of links to individual GitLab UI tabs.
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "Do not include tabs query parameters in links."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#tabs
+level: error
+scope: raw
+raw:
+  - '\[[^\]]+\]\(.*?\.md\?tab=.*?\)'

docs/.vale/gitlab/ToDo.yml

@@ -3,10 +3,10 @@
 #
 # You should not use "To Do", unless it refers to the UI element.
 #
-# For a list of all options, see https://errata-ai.gitbook.io/vale/getting-started/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: 'Use "to-do item" in most cases, or "Add a to do" if referring to the UI button.'
-link: https://docs.gitlab.com/ee/development/documentation/styleguide/index.html#feature-names
+message: "Use 'to-do item' in most cases, or 'Add a to do' if referring to the UI button."
+link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#to-do-item
 level: warning
 ignorecase: false
 swap:

docs/.vale/gitlab/UnclearAntecedent.yml

@@ -3,9 +3,9 @@
 #
 # Checks for words that need a noun for clarity.
 #
-# For a list of all options, see https://docs.errata.ai/vale/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: "'%s' is not precise. Try rewriting with a specific subject and verb."
+message: "Instead of '%s', try starting this sentence with a specific subject and verb."
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#this-these-that-those
 level: warning
 ignorecase: false

docs/.vale/gitlab/Units.yml

@@ -0,0 +1,15 @@
+---
+# Warning: gitlab.Units
+#
+# Recommends a space between a number and a unit of measure.
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "Add a space between the number and the unit in '%s'."
+link: 'https://docs.gitlab.com/ee/development/documentation/styleguide/'
+nonword: true
+level: warning
+ignorecase: true
+tokens:
+  - \d+(?:B|kB|KiB|MB|MiB|GB|GiB|TB|TiB)
+  - \d+(?:ns|ms|μs|s|min|h|d)

docs/.vale/gitlab/Uppercase.yml

@@ -1,13 +1,13 @@
 ---
-# Warning: gitlab.Uppercase
+# Suggestion: gitlab.Uppercase
 #
 # Checks for use of all uppercase letters with unknown reason.
 #
-# For a list of all options, see https://docs.errata.ai/vale/styles.
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: conditional
-message: "'%s' is uppercase. Use lowercase or `backticks` if possible. Otherwise add this word to the rule's exception list."
+message: "Instead of uppercase for '%s', use lowercase or backticks (`) if possible. Otherwise, ask a Technical Writer to add this word or acronym to the rule's exception list."
 link: https://docs.gitlab.com/ee/development/documentation/testing.html#vale-uppercase-acronym-test
-level: warning
+level: suggestion
 ignorecase: false
 # Ensures that the existence of 'first' implies the existence of 'second'.
 first: '\b([A-Z]{3,5})\b'
@@ -16,6 +16,7 @@ second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
 exceptions:
   - ACL
   - AJAX
+  - ALL
   - AMI
   - ANSI
   - APAC
@@ -25,7 +26,9 @@ exceptions:
   - ARN
   - ASCII
   - ASG
+  - AST
   - AWS
+  - BETA
   - BMP
   - BSD
   - CAS
@@ -38,6 +41,7 @@ exceptions:
   - CORE
   - CORS
   - CPU
+  - CRAN
   - CRIME
   - CRM
   - CRUD
@@ -45,16 +49,17 @@ exceptions:
   - CSS
   - CSV
   - CTE
-  - CWE
   - CVE
   - CVS
   - CVSS
+  - CWE
   - DAG
   - DAST
   - DDL
   - DHCP
   - DML
   - DNS
+  - DSN
   - DOM
   - DORA
   - DSA
@@ -144,7 +149,10 @@ exceptions:
   - NOTE
   - NPM
   - NTP
+  - OCI
+  - OIDC
   - OKD
+  - OKR
   - ONLY
   - OSS
   - OTP
@@ -186,6 +194,7 @@ exceptions:
   - SAST
   - SATA
   - SBOM
+  - SBT
   - SCIM
   - SCM
   - SCP

docs/.vale/gitlab/VersionText.yml

@@ -9,9 +9,9 @@
 # - `> 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
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'This introduced-in section is not formatted correctly. Each entry must start with `> -` and long entries must be on one line.'
+message: "Start each entry with `> -`. Keep long entries on one line."
 link: https://docs.gitlab.com/ee/development/documentation/versions.html
 level: error
 scope: raw

docs/.vale/gitlab/VersionTextSingleLine.yml

@@ -3,9 +3,9 @@
 #
 # 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
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: existence
-message: 'Version text with only a single item must not start with a hyphen.'
+message: "Do not use a hyphen '-' in version text if there is only a single item."
 link: https://docs.gitlab.com/ee/development/documentation/versions.html#add-a-version-history-item
 level: error
 scope: raw

docs/.vale/gitlab/Wordy.yml

@@ -3,15 +3,17 @@
 #
 # Suggests shorter versions of wordy phrases.
 #
-# For a list of all options, see https://docs.errata.ai/vale/styles
+# For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
-message: '%s "%s".'
+message: "%s"
 link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html
 level: suggestion
 ignorecase: true
 swap:
-  in order to: "Be concise: use 'to' rather than"
-  needs? to: "Rewrite the sentence, or use 'must', instead of"
-  note that: "Be concise: rewrite the sentence to not use"
-  please: "Remove this word from the sentence: "
-  respectively: "Rewrite the sentence to be more precise, instead of using "
+  a number of: "Specify the number or remove the phrase."
+  as well as: "Use 'and' instead of 'as well as'."
+  note that: "Remove the phrase 'note that'."
+  please: "Use 'please' only if we've inconvenienced the user."
+  respectively: "Remove 'respectively' and list each option instead."
+  and so on: "Remove 'and so on'. Try to use 'like' and provide examples instead."
+  in order to: "Remove 'in order' and leave 'to'."

docs/.vale/gitlab/Zip.yml

@@ -0,0 +1,15 @@
+---
+# Warning: gitlab.Zip
+#
+# Recommends all instances of something.zip be wrapped in backticks
+# due to the .zip top-level domain
+#
+# For a list of all options, see https://vale.sh/docs/topics/styles/
+extends: existence
+message: "Wrap '%s' in backticks to prevent unintentional links to .zip domain names."
+link: 'https://docs.gitlab.com/ee/development/documentation/styleguide/index.md#backticks-in-markdown'
+nonword: true
+level: error
+ignorecase: true
+tokens:
+  - '\b\w*\.zip'

docs/release_process.md

@@ -34,7 +34,7 @@ To manually update the version available through Homebrew:
 
    ```shell
    brew bump-formula-pr --strict glab \
-   --url=https://gitlab.com/gitlab-org/cli/-/archive/v1.23.0/cli-v1.23.0.tar.gz \
+   --url="https://gitlab.com/gitlab-org/cli/-/archive/v1.23.0/cli-v1.23.0.tar.gz" \
    --sha256=4fe9dcecc5e601a849454a3608b47d709b11e2df81527f666b169e0dd362d7df
    ```
 

docs/source/alias/index.md

@@ -21,6 +21,6 @@ Create, list and delete aliases
 
 ## Subcommands
 
-- [delete](delete.md)
-- [list](list.md)
-- [set](set.md)
+- [`delete`](delete.md)
+- [`list`](list.md)
+- [`set`](set.md)

docs/source/ask/index.md

@@ -21,4 +21,4 @@ Generate terminal commands from natural language. (Experimental.)
 
 ## Subcommands
 
-- [git](git.md)
+- [`git`](git.md)

docs/source/auth/index.md

@@ -21,6 +21,6 @@ Manage glab's authentication state
 
 ## Subcommands
 
-- [git-credential](git-credential.md)
-- [login](login.md)
-- [status](status.md)
+- [`git-credential`](git-credential.md)
+- [`login`](login.md)
+- [`status`](status.md)

docs/source/changelog/index.md

@@ -21,4 +21,4 @@ Interact with the changelog API
 
 ## Subcommands
 
-- [generate](generate.md)
+- [`generate`](generate.md)

docs/source/ci/ci/index.md

@@ -29,6 +29,6 @@ glab pipeline ci trace
 
 ## Subcommands
 
-- [lint](lint.md)
-- [trace](trace.md)
-- [view](view.md)
+- [`lint`](lint.md)
+- [`trace`](trace.md)
+- [`view`](view.md)

docs/source/ci/index.md

@@ -34,14 +34,14 @@ pipeline
 
 ## Subcommands
 
-- [artifact](artifact.md)
-- [ci](ci/index.md)
-- [delete](delete.md)
-- [get](get.md)
-- [lint](lint.md)
-- [list](list.md)
-- [retry](retry.md)
-- [run](run.md)
-- [status](status.md)
-- [trace](trace.md)
-- [view](view.md)
+- [`artifact`](artifact.md)
+- [`ci`](ci/index.md)
+- [`delete`](delete.md)
+- [`get`](get.md)
+- [`lint`](lint.md)
+- [`list`](list.md)
+- [`retry`](retry.md)
+- [`run`](run.md)
+- [`status`](status.md)
+- [`trace`](trace.md)
+- [`view`](view.md)

docs/source/cluster/agent/index.md

@@ -27,6 +27,6 @@ Manage GitLab Agents for Kubernetes
 
 ## Subcommands
 
-- [get-token](get-token.md)
-- [list](list.md)
-- [update-kubeconfig](update-kubeconfig.md)
+- [`get-token`](get-token.md)
+- [`list`](list.md)
+- [`update-kubeconfig`](update-kubeconfig.md)

docs/source/cluster/index.md

@@ -27,4 +27,4 @@ Manage GitLab Agents for Kubernetes and their clusters
 
 ## Subcommands
 
-- [agent](agent/index.md)
+- [`agent`](agent/index.md)

docs/source/completion/index.md

@@ -96,7 +96,7 @@ glab completion -s powershell | Out-String | Invoke-Expression
 ```
 
 To load completions for every new session, add the output of the above command
-to your powershell profile.
+to your PowerShell profile.
 
 When installing glab through a package manager, however, it's possible that
 no additional shell configuration is necessary to gain completion support.

docs/source/config/index.md

@@ -49,6 +49,6 @@ conf
 
 ## Subcommands
 
-- [get](get.md)
-- [init](init.md)
-- [set](set.md)
+- [`get`](get.md)
+- [`init`](init.md)
+- [`set`](set.md)

docs/source/incident/index.md

@@ -34,10 +34,10 @@ glab incident list
 
 ## Subcommands
 
-- [close](close.md)
-- [list](list.md)
-- [note](note.md)
-- [reopen](reopen.md)
-- [subscribe](subscribe.md)
-- [unsubscribe](unsubscribe.md)
-- [view](view.md)
+- [`close`](close.md)
+- [`list`](list.md)
+- [`note`](note.md)
+- [`reopen`](reopen.md)
+- [`subscribe`](subscribe.md)
+- [`unsubscribe`](unsubscribe.md)
+- [`view`](view.md)

docs/source/index.md

@@ -80,6 +80,5 @@ to send us feedback.
 ## Related topics
 
 - [Install the CLI](https://gitlab.com/gitlab-org/cli/-/blob/main/README.md#installation)
-- [Documentation](https://gitlab.com/gitlab-org/cli/-/tree/main/docs/source)
 - The extension source code is available in the
   [`cli`](https://gitlab.com/gitlab-org/cli/) project.

docs/source/issue/board/index.md

@@ -27,5 +27,5 @@ Work with GitLab Issue Boards in the given project.
 
 ## Subcommands
 
-- [create](create.md)
-- [view](view.md)
+- [`create`](create.md)
+- [`view`](view.md)

docs/source/issue/index.md

@@ -37,14 +37,14 @@ glab issue note -m "closing because !123 was merged" <issue number>
 
 ## Subcommands
 
-- [board](board/index.md)
-- [close](close.md)
-- [create](create.md)
-- [delete](delete.md)
-- [list](list.md)
-- [note](note.md)
-- [reopen](reopen.md)
-- [subscribe](subscribe.md)
-- [unsubscribe](unsubscribe.md)
-- [update](update.md)
-- [view](view.md)
+- [`board`](board/index.md)
+- [`close`](close.md)
+- [`create`](create.md)
+- [`delete`](delete.md)
+- [`list`](list.md)
+- [`note`](note.md)
+- [`reopen`](reopen.md)
+- [`subscribe`](subscribe.md)
+- [`unsubscribe`](unsubscribe.md)
+- [`update`](update.md)
+- [`view`](view.md)

docs/source/label/index.md

@@ -27,5 +27,5 @@ Manage labels on remote
 
 ## Subcommands
 
-- [create](create.md)
-- [list](list.md)
+- [`create`](create.md)
+- [`list`](list.md)

docs/source/mr/index.md

@@ -36,23 +36,23 @@ glab mr note -m "needs to do X before it can be merged" branch-foo
 
 ## Subcommands
 
-- [approve](approve.md)
-- [approvers](approvers.md)
-- [checkout](checkout.md)
-- [close](close.md)
-- [create](create.md)
-- [delete](delete.md)
-- [diff](diff.md)
-- [for](for.md)
-- [issues](issues.md)
-- [list](list.md)
-- [merge](merge.md)
-- [note](note.md)
-- [rebase](rebase.md)
-- [reopen](reopen.md)
-- [revoke](revoke.md)
-- [subscribe](subscribe.md)
-- [todo](todo.md)
-- [unsubscribe](unsubscribe.md)
-- [update](update.md)
-- [view](view.md)
+- [`approve`](approve.md)
+- [`approvers`](approvers.md)
+- [`checkout`](checkout.md)
+- [`close`](close.md)
+- [`create`](create.md)
+- [`delete`](delete.md)
+- [`diff`](diff.md)
+- [`for`](for.md)
+- [`issues`](issues.md)
+- [`list`](list.md)
+- [`merge`](merge.md)
+- [`note`](note.md)
+- [`rebase`](rebase.md)
+- [`reopen`](reopen.md)
+- [`revoke`](revoke.md)
+- [`subscribe`](subscribe.md)
+- [`todo`](todo.md)
+- [`unsubscribe`](unsubscribe.md)
+- [`update`](update.md)
+- [`view`](view.md)

docs/source/release/index.md

@@ -27,9 +27,9 @@ Manage GitLab releases
 
 ## Subcommands
 
-- [create](create.md)
-- [delete](delete.md)
-- [download](download.md)
-- [list](list.md)
-- [upload](upload.md)
-- [view](view.md)
+- [`create`](create.md)
+- [`delete`](delete.md)
+- [`download`](download.md)
+- [`list`](list.md)
+- [`upload`](upload.md)
+- [`view`](view.md)

docs/source/repo/index.md

@@ -27,14 +27,14 @@ project
 
 ## Subcommands
 
-- [archive](archive.md)
-- [clone](clone.md)
-- [contributors](contributors.md)
-- [create](create.md)
-- [delete](delete.md)
-- [fork](fork.md)
-- [list](list.md)
-- [mirror](mirror.md)
-- [search](search.md)
-- [transfer](transfer.md)
-- [view](view.md)
+- [`archive`](archive.md)
+- [`clone`](clone.md)
+- [`contributors`](contributors.md)
+- [`create`](create.md)
+- [`delete`](delete.md)
+- [`fork`](fork.md)
+- [`list`](list.md)
+- [`mirror`](mirror.md)
+- [`search`](search.md)
+- [`transfer`](transfer.md)
+- [`view`](view.md)

docs/source/schedule/index.md

@@ -34,7 +34,7 @@ skd
 
 ## Subcommands
 
-- [create](create.md)
-- [delete](delete.md)
-- [list](list.md)
-- [run](run.md)
+- [`create`](create.md)
+- [`delete`](delete.md)
+- [`list`](list.md)
+- [`run`](run.md)

docs/source/snippet/index.md

@@ -34,4 +34,4 @@ glab snippet create --title "Title of the snippet" --filename "main.go"
 
 ## Subcommands
 
-- [create](create.md)
+- [`create`](create.md)

docs/source/ssh-key/index.md

@@ -27,7 +27,7 @@ Manage SSH keys registered with your GitLab account.
 
 ## Subcommands
 
-- [add](add.md)
-- [delete](delete.md)
-- [get](get.md)
-- [list](list.md)
+- [`add`](add.md)
+- [`delete`](delete.md)
+- [`get`](get.md)
+- [`list`](list.md)

docs/source/user/index.md

@@ -21,4 +21,4 @@ Interact with user
 
 ## Subcommands
 
-- [events](events.md)
+- [`events`](events.md)

docs/source/variable/index.md

@@ -33,9 +33,9 @@ var
 
 ## Subcommands
 
-- [delete](delete.md)
-- [export](export.md)
-- [get](get.md)
-- [list](list.md)
-- [set](set.md)
-- [update](update.md)
+- [`delete`](delete.md)
+- [`export`](export.md)
+- [`get`](get.md)
+- [`list`](list.md)
+- [`set`](set.md)
+- [`update`](update.md)