Merge branch 'eread/vale-and-markdown-refresh-docs' into 'master'

Vale and Markdown rule refresh for project

See merge request https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/7419

Merged-by: Marcel Amirault <mamirault@gitlab.com>
Approved-by: Balasankar 'Balu' C <balasankar@gitlab.com>
Approved-by: Marcel Amirault <mamirault@gitlab.com>
Co-authored-by: Evan Read <eread@gitlab.com>

Author: Ravlen

.tool-versions

@@ -1,2 +1,2 @@
 ruby 3.1.4
-vale 2.29.6
+vale 3.0.7

doc/.vale/gitlab/HistoryItems.yml

@@ -0,0 +1,13 @@
+---
+# Warning: gitlab.HistoryItems
+#
+# Ensures history items are properly formatted.
+#
+extends: existence
+message: "History items must always start with '> -', one item per line, even if there is only one item."
+link: https://docs.gitlab.com/ee/development/documentation/versions.html#add-a-version-history-item
+level: error
+scope: raw
+raw:
+  - '(?m)(?<=^#+[^\n]*\n\n)> [^-]|'
+  - '^> - [^\n]*\n[^\n>`]'

doc/.vale/gitlab/LatinTerms.yml

@@ -15,3 +15,4 @@ swap:
   e\. g\.: for example
   i\.e\.: that is
   i\. e\.: that is
+  via: "with', 'through', or 'by using"

doc/.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:'

doc/.vale/gitlab/SubstitutionWarning.yml

@@ -30,12 +30,14 @@ swap:
   ex: "for example"
   file name: "filename"
   filesystem: "file system"
+  fullscreen: "full screen"
   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"
+  machine-learning: "machine learning"
   modal dialog: "dialog"
   modal window: "dialog"
   modal: "dialog"
@@ -47,6 +49,8 @@ swap:
   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"
@@ -59,6 +63,6 @@ swap:
   sub-group: "subgroup"
   sub-groups: "subgroups"
   timezone: "time zone"
-  utilize: "use"
+  utiliz(?:es?|ing): "use"
   we recommend: "you should"
   within: "in"

doc/.vale/gitlab/Substitutions.yml

@@ -7,58 +7,61 @@
 # For a list of all options, see https://vale.sh/docs/topics/styles/
 extends: substitution
 message: "Use '%s' instead of '%s'."
-link: https://about.gitlab.com/handbook/communication/#top-misused-terms
+link: https://handbook.gitlab.com/handbook/communication/top-misused-terms/
 level: error
 ignorecase: true
 swap:
+  admin user: administrator
+  admin users: administrators
+  administrator permission: administrator access
+  administrator permissions: administrator access
+  administrator role: administrator access
+  at least the Owner role: the Owner role
+  can login: can log in
+  can log-in: can log in
+  can signin: can sign in
+  can sign-in: can sign in
   codequality: code quality
   Customer [Pp]ortal: Customers Portal
+  developer access: the Developer role
+  developer permission: the Developer role
+  developer permissions: the Developer role
   disallow: prevent
+  '(?<!GitLab )Duo': GitLab Duo
   frontmatter: front matter
+  GitLab self hosted: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
+  GitLab self-hosted: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
   GitLabber: GitLab team member
   GitLabbers: GitLab team members
   GitLab-shell: GitLab Shell
   gitlab omnibus: Linux package
+  golang: Go
+  guest access: the Guest role
+  guest permission: the Guest role
+  guest permissions: the Guest role
+  maintainer access: the Maintainer role
+  maintainer permission: the Maintainer role
+  maintainer permissions: the Maintainer role
+  owner access: the Owner role
+  owner permission: the Owner role
+  owner permissions: the Owner role
   param: parameter
   params: parameters
   pg: PostgreSQL
   'postgres$': PostgreSQL
-  golang: Go
   raketask: Rake task
   raketasks: Rake tasks
   rspec: RSpec
-  self hosted: self-managed
-  self-hosted: self-managed
+  reporter access: the Reporter role
+  reporter permission: the Reporter role
+  reporter permissions: the Reporter role
+  self hosted GitLab: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
+  self-hosted GitLab: GitLab self-managed # https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.html#gitlab-self-managed
   styleguide: style guide
+  the administrator access level: administrator access
   to login: to log in
-  can login: can log in
   to log-in: to log in
-  can log-in: can log in
   to signin: to sign in
-  can signin: can sign in
   to sign-in: to sign in
-  can sign-in: can sign in
   x509: X.509
   yml: YAML
-  admin user: administrator
-  admin users: administrators
-  administrator permission: administrator access
-  administrator permissions: administrator access
-  administrator role: administrator access
-  the administrator access level: administrator access
-  developer access: the Developer role
-  developer permission: the Developer role
-  developer permissions: the Developer role
-  guest access: the Guest role
-  guest permission: the Guest role
-  guest permissions: the Guest role
-  maintainer access: the Maintainer role
-  maintainer permission: the Maintainer role
-  maintainer permissions: the Maintainer role
-  owner access: the Owner role
-  owner permission: the Owner role
-  owner permissions: the Owner role
-  reporter access: the Reporter role
-  reporter permission: the Reporter role
-  reporter permissions: the Reporter role
-  at least the Owner role: the Owner role

doc/.vale/gitlab/Wordy.yml

@@ -10,6 +10,7 @@ link: https://docs.gitlab.com/ee/development/documentation/styleguide/word_list.
 level: suggestion
 ignorecase: true
 swap:
+  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."

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

@@ -109,6 +109,7 @@ bugfixed
 bugfixes
 bugfixing
 Bugzilla
+Buildah
 Buildkite
 buildpack
 buildpacks
@@ -176,6 +177,7 @@ Codecov
 codenames
 Codepen
 CodeSandbox
+Codey
 Cognito
 Coinbase
 colocate
@@ -282,6 +284,7 @@ devfiles
 DevOps
 Dhall
 dialogs
+Diffblue
 disambiguates
 discoverability
 dismissable
@@ -350,6 +353,7 @@ Fastly
 Fastzip
 favicon
 favorited
+Fediverse
 ffaker
 Figma
 Filebeat
@@ -370,6 +374,7 @@ Flycheck
 focusable
 Forgerock
 formatters
+Fortanix
 Fortinet
 FQDNs
 FreshBooks
@@ -525,6 +530,7 @@ LaunchDarkly
 ldapsearch
 Lefthook
 Leiningen
+Lemmy
 libFuzzer
 Libgcrypt
 Libravatar
@@ -644,6 +650,7 @@ OmniAuth
 onboarding
 OpenID
 OpenShift
+OpenTelemetry
 Opsgenie
 Opstrace
 ORMs
@@ -879,7 +886,6 @@ sharded
 sharding
 SHAs
 shfmt
-Shimo
 Shippo
 Shopify
 Sidekiq
@@ -958,6 +964,7 @@ subqueried
 subqueries
 subquery
 subquerying
+Subreddit
 substring
 substrings
 subtask

gitlab-ci-config/gitlab-com.yml

@@ -308,7 +308,7 @@ rubocop:
 
 # Perform documentation linting on Markdown files
 docs-lint markdown:
-  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
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-markdown:alpine-3.19-vale-3.0.7-markdownlint-0.39.0-markdownlint2-0.12.1
   stage: check
   cache: {}
   needs: []
@@ -325,18 +325,22 @@ docs-lint markdown:
 
 # Perform link checks on published HTML files
 docs-lint links:
-  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-html:alpine-3.18-ruby-3.2.2-08fa6df8
+  image: registry.gitlab.com/gitlab-org/gitlab-docs/lint-html:alpine-3.19-ruby-3.2.3-eee6c4c0
   stage: check
   cache: {}
   needs: []
   before_script: []
   script:
-    # Prepare docs for build
-    - mv doc/ /tmp/gitlab-docs/content/omnibus
+    # Put documentation in location expected by nanoc and configured in nanoc.yaml. For more information, see:
+    # https://gitlab.com/gitlab-org/gitlab-docs/-/blob/eee6c4c03621ff13743828ad74a8f0e8b96dfe7c/nanoc.yaml#L43
+    - mkdir /tmp/omnibus-gitlab
+    - mv doc/ /tmp/omnibus-gitlab
     - cd /tmp/gitlab-docs
     # Build HTML from Markdown
     - make compile
     # Check the internal links and anchors (in parallel)
+    # Links from the home page aren't checked because they aren't rendered here. For information, see:
+    # https://gitlab.com/gitlab-org/gitlab-docs/-/blob/eee6c4c03621ff13743828ad74a8f0e8b96dfe7c/content/index.erb#L6
     - "parallel time bundle exec nanoc check ::: internal_links internal_anchors"
   rules:
     - if: '$PIPELINE_TYPE =~ /_TEST_PIPELINE$/'