Add linters for consistent docs product language

Closes #19214

Maintaining a consistent language for talking about Teleport products is
important for ensuring clarity in the documentation. This change adds
rules to our Vale linting config for docs to help maintain a consistent
product language:

- **Teleport account URL examples:** Require `example.teleport.sh`
  unless the text is mentioning the status page.
- **Service names:** Require these to be capitalized.
- **Enforce consistency in other areas where we often get
  discrepancies:** e.g., "Auth Service instances" instead of "auth
  servers".

This change also renames the `messaging` style rule to
`consistent-terms` so we don't have a `messaging.messaging` rule.

Note that these linters overlap with similar ones that we run from the
`gravitational/docs` repo. The plan is to remove the latter once we
merge the linters here.

.github/vale-styles/examples/teleport-accounts.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: "Incorrect example of a Teleport account URL. Use %s instead of %s."
+level: error
+scope:
+ - raw
+ignorecase: true
+swap:
+  - 'https://(?!status|example)\w+.teleport\.sh': 'example.teleport.sh (or status.teleport.sh for the status page)'

.github/vale-styles/messaging/capitalize-services.yml

@@ -0,0 +1,21 @@
+extends: existence
+scope:
+  - heading
+  - table
+  - list
+  - paragraph
+message: "Capitalize the names of Teleport services (%s is incorrect). See the Core Concepts page (https://goteleport.com/docs/core-concepts/) for service names."
+level: error
+ignorecase: false
+tokens:
+  - machine id
+  - database service
+  - db service
+  - 'app(lication) service'
+  - desktop service
+  - kubernetes service
+  - ssh service
+  - discovery service
+  - auth service
+  # Allow for mentions of a local proxy service, but not "proxy service".
+  - '(?<!local )proxy service'

.github/vale-styles/messaging/consistent-terms.yml

@@ -0,0 +1,22 @@
+# The consistent-terms rule ensures that terms with frequently used variations
+# appear consistently in the docs.
+extends: substitution
+scope:
+  - heading
+  - table
+  - list
+  - paragraph
+message: For consistent product messaging in the docs, use '%s' instead of '%s'.
+level: error
+# Ignoring case because this rule is about word choice, rather than its
+# presentation/format.
+ignorecase: true
+swap:
+  2FA: MFA
+  'second[ -]factor': multi-factor
+  'auth and proxy': Auth Service and Proxy Service
+  'auth server|auth node': \"Auth Service\" (or \"Auth Service instance\" for a specific node)
+  'Auth Services': Auth Service instances
+  'Teleport open source|open source Teleport': Teleport Community Edition
+  'OSS Teleport|Teleport OSS': Teleport Community Edition
+  'Teleport Cloud': \"Teleport Team\" or \"Teleport Enterprise Cloud\"

.github/workflows/doc-tests.yaml

@@ -112,7 +112,14 @@ jobs:
         uses: errata-ai/vale-action@3f7188c866bcb3259339a09f517d7c4a8838303c # reviewdog
         with:
           version: 2.30.0
+          # Take the comma-separated list of files returned by the "Check for
+          # relevant changes" job.
           separator: ","
           files: ${{ needs.changes.outputs.changed_files }}
+          # Report all results in a file modified in the PR, even if it wasn't
+          # touched by the diff. This way, we can gradually implement a style
+          # guide across the docs: docs authors do a little bit of extra work,
+          # but aren't responsible for entire docs site.
+          filter_mode: file
           fail_on_error: true
 

.vale.ini

@@ -5,4 +5,4 @@ MinAlertLevel = suggestion
 mdx = md
 
 [*.md]
-BasedOnStyles = messaging
+BasedOnStyles = messaging,examples