From b150cddf1a090584feb82d6c7dc23759ce2d4253 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 54df4b0743ef2..617d3635bc316 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
@@ -114,34 +115,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 = "{/*,*/}"