Add a GHA job for linting docs prose (#35792)

* Add a GHA job for linting docs prose

This change helps ensure that the documentation uses consistent product
language and style without requiring manual intervention by members of
the Documentation Team. To do so, it introduces automated linting using
the Vale prose linting tool. It includes one style rule--making sure
docs pages say "MFA" instead of "2FA"--as a proof of concept.

The main advantages of Vale are that:
- Vale includes logic for parsing Markdown and running linters out of
  the box.
- Vale has a flexible configuration language that makes style rules easy
  to define.

This is in contrast to the linters we wrote in `gravitational/docs`,
where logic for traversing Markdown ASTs is tightly coupled with the
definition of style rules, making these linters difficult to extend.

Because the point of using Vale is to make it easy to define
comprehensive style rules, the GitHub Actions job that runs Vale only
runs it against files changed by a PR. This means that, when we
introduce a new style rule, we won't need to rectify all violations in
the docs before allowing authors to merge their changes.

Note that the GHA config introduces a separate job for Vale. This is
because the `errata-ai/vale-action` action does not allow the
configuration to set a working directory, and the `Lint (Docs)` job
organizes the `teleport` repo into a `gravitational/docs` submodule,
making the Vale action incompatible with the `Lint (Docs)` job.

Also note that we cannot reuse the `changed_files` output of the `Check
for relevant changes` step between the Vale job and the `Lint (Docs)`
job without adding some complexity, since the Vale job doesn't accept a
space as a delimiter for file paths, and `remark` doesn't accept
non-spaces. While we could look into checking only changed files in
`Lint (Docs)` in the future, this change refrains from doing so to keep
things simple.

* Respond to zmb3 feedback

- Remove the `merge_group` trigger since this job runs on PRs anyway.
- Only run the docs prose linter if relevant files have changed (use the
  same `if` condition as the `doc-tests` job).

* Respond to rosstimothy feedback

Remove quotes around a config key

* Run Lint (Docs) on merge_group

However, ensure that the prose linter only runs on pull_request to
prevent unnecessary work.

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

@@ -0,0 +1,12 @@
+extends: substitution
+scope:
+  - heading
+  - table
+  - list
+  - paragraph
+message: For consistent product messaging in the docs, use '%s' instead of '%s'.
+level: error
+ignorecase: false
+swap:
+  2FA: MFA
+  '[Ss]econd-?factor': multi-factor

.github/workflows/doc-tests.yaml

@@ -5,7 +5,6 @@ on:
 
   merge_group:
 
-
 jobs:
   changes:
     name: Check for relevant changes
@@ -14,6 +13,7 @@ jobs:
       pull-requests: read
     outputs:
       changed: ${{ steps.changes.outputs.changed }}
+      changed_files: ${{ steps.changes.outputs.changed_files }}
     steps:
       - name: Checkout
         if: ${{ github.event_name == 'merge_group' }}
@@ -23,6 +23,7 @@ jobs:
         with:
           base: ${{ github.event.pull_request.base.ref || github.event.merge_group.base_ref }}
           ref: ${{ github.event.pull_request.head.ref || github.event.merge_group.head_ref }}
+          list-files: csv
           filters: |
             changed:
               - '.github/workflows/doc-tests.yaml'
@@ -78,6 +79,7 @@ jobs:
           echo "" > .gitmodules
           rm -rf content/*
           cd content
+          # Add a submodule at docs/content/teleport
           git submodule add --force -b $BRANCH -- https://github.com/gravitational/teleport
           cd $GITHUB_WORKSPACE/docs
           echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
@@ -92,3 +94,25 @@ jobs:
 
       - name: Test the docs build
         run: cd $GITHUB_WORKSPACE/docs && yarn install && yarn build
+
+  stylecheck:
+    name: Lint docs prose style
+    runs-on: ubuntu-latest
+    needs: changes
+    if: ${{ !startsWith(github.head_ref, 'dependabot/') && needs.changes.outputs.changed == 'true' && github.event_name == 'pull_request' }}
+    permissions:
+      pull-requests: read
+    steps:
+      - name: Check out the teleport repo
+        uses: actions/checkout@v4
+        with:
+          repository: "gravitational/teleport"
+
+      - name: Run the linter
+        uses: errata-ai/vale-action@c99f2dfd2aeaedb3d4bb16f385841830b9164d31 # reviewdog
+        with:
+          version: 2.30.0
+          separator: ","
+          files: ${{ needs.changes.outputs.changed_files }}
+          fail_on_error: true
+

.vale.ini

@@ -0,0 +1,8 @@
+StylesPath = .github/vale-styles
+MinAlertLevel = suggestion
+
+[formats]
+mdx = md
+
+[*.md]
+BasedOnStyles = messaging