From 9ff8b17722d83057c8606580f5dd568fdc5572eb Mon Sep 17 00:00:00 2001
From: Paul Gottschling <paul.gottschling@goteleport.com>
Date: Tue, 22 Oct 2024 13:37:24 -0400
Subject: [PATCH] Make the Vale prose linter required

This change makes the prose linting step part of the required Lint
(Docs) job.

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 */}
```

This change updates the version of Vale used by the linting job to
3.9.0, and includes custom comment delimiters in the configuration.
---
 .github/workflows/doc-tests.yaml | 30 +++++++++---------------------
 docs/.vale.ini                   |  1 +
 2 files changed, 10 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/doc-tests.yaml b/.github/workflows/doc-tests.yaml
index e4463ddba2530..2a622ee0a26a6 100644
--- a/.github/workflows/doc-tests.yaml
+++ b/.github/workflows/doc-tests.yaml
@@ -39,6 +39,7 @@ jobs:
 
     permissions:
       contents: read
+      pull-requests: read
 
     steps:
       - name: Checkout
@@ -109,34 +110,21 @@ jobs:
         working-directory: 'docs'
         run: yarn markdown-lint
 
-      - name: Test the docs build
-        working-directory: docs
-        run: 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
+      - 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
diff --git a/docs/.vale.ini b/docs/.vale.ini
index 9620898c3adba..024986fb2b30a 100644
--- a/docs/.vale.ini
+++ b/docs/.vale.ini
@@ -6,3 +6,4 @@ mdx = md
 
 [*.md]
 BasedOnStyles = messaging,examples,3rd-party-products,structure
+CommentDelimiters = "{/*,*/}"