Make the Vale prose linter required

As of Vale 3.8.0, it is possible to set custom comment delimiters so an
author can temporarily disable a style rule within an MDX docs page. For
example, an author can ignore the `protocol-products` rule by including
this:

```text
{/* vale messaging.protocol-products = NO */}

This paragraph is about server access.

{/* vale messaging.protocol-products = YES */}
```

As a result, we can require the Vale prose linter without worrying about
false positives.

This change updates the version of Vale used by the linting job to
3.8.0.

It also makes the prose linting step part of the required Lint (Docs)
job. To do so, it overrides `yarn git-update` to ignore submodules,
checks out `gravitational/teleport` at the current branch, and copies
the `teleport` clone into the directory where the docs engine expects
submodules. It then edits the working directory of the Vale job.

Since the Vale job only ran on `pull_request` events, and not
`merge_group`, this change also adjusts all of `Lint (Docs)` to run on
`pull_request`.

Finally, this change edits the level of some Vale styles:
- `error` (which causes Vale to exit with a nonzero status code): styles
  where we want to ensure consistency/correctness, and where it is
  possible to disable the style using comments.
- `warning` (which causes Vale to print a message but exit with a zero
  status code): style rules that an author might need to ignore. This
  includes style rules with the `raw` scope, which cannot be disabled
  using comments.

.github/workflows/doc-tests.yaml

@@ -39,13 +39,20 @@ jobs:
 
     permissions:
       contents: read
+      pull-requests: read
 
     steps:
       - name: Checkout
         uses: actions/checkout@v4
         with:
-          repository: "gravitational/docs"
-          path: "docs"
+          repository: 'gravitational/teleport'
+          path: 'teleport'
+
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          repository: 'gravitational/docs'
+          path: 'docs'
 
       # Cache node_modules. Unlike the example in the actions/cache repo, this
       # caches the node_modules directory instead of the yarn cache. This is
@@ -69,6 +76,7 @@ jobs:
         run: yarn install
 
       - name: Prepare docs site configuration
+        working-directory: docs
         # The environment we use for linting the docs differs from the one we
         # use for the live docs site in that we only test a single version of
         # the content.
@@ -83,63 +91,40 @@ jobs:
         # of gravitational/teleport. We override this in order to build only a
         # single version of the docs.
         run: |
-          if [ $GITHUB_EVENT_NAME = "pull_request" ]; then
-            BRANCH=$GITHUB_HEAD_REF;
-          elif [ $GITHUB_EVENT_NAME = "merge_group" ]; then
-            # GitHub populates $GITHUB_REF with:
-            # refs/heads/gh-readonly-queue/<base branch>/pr-<PR number>-<SHA>
-            #
-            # We strip the "refs/heads/" prefix so we can check out the branch.
-            BRANCH=$(echo $GITHUB_REF | sed -E "s|refs/heads/(.*)|\1|")
-          else
-            echo "Unexpected event name: $GITHUB_EVENT_NAME";
-            exit 1;
-          fi
-
-          cd $GITHUB_WORKSPACE/docs
           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
+          # Rather than using a submodule, copy the teleport source into the
+          # content directory.
+          cp -r $GITHUB_WORKSPACE/teleport $GITHUB_WORKSPACE/docs/content
           cd $GITHUB_WORKSPACE/docs
-          echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"$BRANCH\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
+          echo "{\"versions\": [{\"name\": \"teleport\", \"branch\": \"teleport\", \"deprecated\": false}]}" > $GITHUB_WORKSPACE/docs/config.json
+          cat <<< "$(jq '.scripts."git-update" = "echo Skipping submodule update"' package.json)" > package.json
           yarn build-node
 
       - name: Check spelling
-        run: cd $GITHUB_WORKSPACE/docs && yarn spellcheck content/teleport
-
-      - name: Lint the docs
-        run: cd $GITHUB_WORKSPACE/docs && yarn markdown-lint
-
-      - name: Test the docs build
-        working-directory: docs
-        run: yarn build
+        working-directory: 'docs'
+        run: yarn spellcheck content/teleport
 
-  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: Lint docs formatting
+        working-directory: 'docs'
+        run: yarn markdown-lint
 
-      - name: Run the linter
+      - name: Lint docs prose
         uses: errata-ai/vale-action@d89dee975228ae261d22c15adcd03578634d429c # v2.1.1
         with:
-          version: 2.30.0
+          version: 3.9.0
           # Take the comma-separated list of files returned by the "Check for
           # relevant changes" job.
-          separator: ","
+          separator: ','
+          workdir: '${{ github.workspace }}/docs/content/teleport'
           files: ${{ needs.changes.outputs.changed_files }}
           # Restrict the linter to lines modified/added by a PR, not entire
           # changed files.
           filter_mode: added
           fail_on_error: true
-          vale_flags: "--config=docs/.vale.ini"
+          vale_flags: '--config=${{ github.workspace }}/docs/content/teleport/docs/.vale.ini'
 
+      - name: Test the docs build
+        working-directory: 'docs'
+        run: yarn build

docs/.vale.ini

@@ -6,3 +6,4 @@ mdx = md
 
 [*.md]
 BasedOnStyles = messaging,examples,3rd-party-products,structure
+CommentDelimiters = "{/*,*/}"

docs/vale-styles/3rd-party-products/aws-vs-amazon.yml

@@ -15,8 +15,7 @@
 #   /^AWS /{ print gensub(/AWS (.*)/,"  \"Amazon \\1\"","1") ": " $0}'
 extends: substitution
 message: "Incorrect AWS product name. Use %s instead of %s."
-scope: raw
-level: warning
+level: error
 ignorecase: true
 swap:
   "Amazon Account Management": AWS Account Management

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

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

docs/vale-styles/messaging/edition-names.yml

@@ -1,13 +1,7 @@
 extends: existence
 scope:
-  # Using the raw scope so we can catch instances in TabItem labels.
-  - raw
 message: '"%s" is no longer a recognized Teleport edition. Use "Teleport Enterprise (Self-Hosted)" or "Teleport Enterprise (Cloud)" instead. If the hosting type is not important in a given sentence, there is no need to specify it, and you can use "Teleport Enterprise".'
 level: error
-ignorecase: false
+ignorecase: true
 tokens:
-  # Adding the pattern '[ \t]*\n?[ \t]*' between each word since we are using the raw
-  # scope. This lets use catch violations that span two lines (i.e., that occupy
-  # the same paragraph).
-  - 'Teleport[ \t]*\n?[ \t]*Cloud'
-  - 'Teleport[ \t]*\n?[ \t]*Enterprise[ \t]*\n?[ \t]*Cloud'
+  - 'Teleport Enterprise Cloud'

docs/vale-styles/messaging/subjective-terms.yml

@@ -1,7 +1,7 @@
 extends: existence
 link: "https://github.com/gravitational/docs/blob/main/docs-contributors/style-guide.md#voice"
-message: "Avoid using '%s' as a qualifier, since it is subject to interpretation. Use more technically precise terms instead."
-level: error
+message: "Consider avoiding '%s' as a qualifier, since it is subject to interpretation. Use more technically precise terms instead."
+level: warning
 ignorecase: true
 tokens:
   - "powerful(ly)?"

docs/vale-styles/structure/architecture-h2.yml

@@ -6,7 +6,7 @@
 # This style defines a how-to guide as any guide that includes at least one H2
 # beginning "Step [0-9]". 
 extends: script
-level: error
+level: warning
 message: "In a how-to guide, the first H2-level section must be called `## How it works`. Use this section to include 1-3 paragraphs that describe the high-level architecture of the setup shown in the guide, i.e., which infrastructure components are involved and how they communicate. If there is already architectural information in the guide, include it in a `## How it works` section."
 scope: raw
 script: |

docs/vale-styles/structure/intro-paragraph.yml

@@ -1,7 +1,7 @@
 # This style enforces the presence of an introductory paragraph before the first
 # H2 of a docs page.
 extends: script
-level: error
+level: warning
 message: There must be a brief intro paragraph before the first H2-level section of a docs page. Use this to describe the purpose of the guide so a reader can determine whether they should continue reading. If the guide introduces a feature, describe the purpose and benefits of the feature. If there is already an "Introduction" H2 or similar, remove the heading.
 scope: raw
 script: |

docs/vale-styles/structure/step-numbering.yml

@@ -6,7 +6,7 @@
 # such as the presence of step headings in how-to guides and the formatting of
 # step headings.
 extends: script
-level: error
+level: warning
 message: Guides that include H2 sections named after numbered steps (e.g., "Step 1/5") must have the expected sequence of numbers and accurate total numbers of steps. This heading either has an unexpected step number or an unexpected total number of steps.
 scope: raw
 script: |