fix: enable vale workflow correctly to review documentation changes (#10211)

* fix: add config path to Vale workflow

* test: add doc to test Vale linting

* Update docs-website-vale.yml

* test single docs folder

* adjust rules

* file for testing vale comments

* adjust rules

* abbreviation rule swap

* simpler test file

* adjust more rules after review

* new testing mdx file

* Delete test-component-page.mdx

Author: dfokina

.github/workflows/docs-website-vale.yml

@@ -32,9 +32,8 @@ jobs:
       - name: Vale
         uses: errata-ai/vale-action@v2
         with:
-          files: |
-            docs-website/docs
-            docs-website/versioned_docs
+          vale_flags: "--config=docs-website/.vale.ini"
+          files: docs-website/docs
           reporter: github-pr-review
           fail_on_error: false
         env:

docs-website/.vale.ini

@@ -5,3 +5,17 @@ MinAlertLevel = suggestion
 
 [*.{md,mdx}]
 BasedOnStyles = Vale, Google, MyStyle
+
+# Disable Vale's built-in spell checker (flags technical terms like "embedders")
+Vale.Spelling = NO
+
+# Disable Google.Headings - conflicts with MyStyle.Headings (title case vs sentence case)
+# and doesn't handle PascalCase component names well
+Google.Headings = NO
+
+# Disable Google.Passive - too noisy for technical documentation where passive voice
+# is often appropriate and hard to rephrase
+Google.Passive = NO
+
+# Disable Google.Acronyms - AI/ML acronyms like RAG, LLM are well-known to our audience
+Google.Acronyms = NO

docs-website/.vale/styles/Google/Latin.yml

@@ -9,3 +9,5 @@ action:
 swap:
   '\b(?:eg|e\.g\.)[\s,]': for example
   '\b(?:ie|i\.e\.)[\s,]': that is
+  '\betc\.': and so on
+  '\bvs\.': versus

docs-website/.vale/styles/MyStyle/Abbreviations.yml

@@ -0,0 +1,9 @@
+extends: substitution
+message: "Use '%s' instead of the abbreviation '%s'."
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  '\bmisc\b': miscellaneous
+  '\bdoc\b': document

docs-website/.vale/styles/MyStyle/AvoidJust.yml

@@ -0,0 +1,7 @@
+extends: existence
+message: "Avoid 'please' in instructions—it can make actions seem optional. Use imperative instead."
+level: warning
+ignorecase: true
+scope: text
+tokens:
+  - please

docs-website/.vale/styles/MyStyle/AvoidPlease.yml

@@ -1,14 +1,13 @@
 extends: existence
-message: "Prefer second person (e.g., 'you') instead of '%s'."
+message: "Prefer second person ('you') instead of '%s'."
 level: warning
-nonword: true
 scope: text
 tokens:
   - the user
   - the customer
   - the client
-  - he
-  - she
-  - his
-  - her
+  - '\bhe\b'
+  - '\bshe\b'
+  - '\bhis\b'
+  - '\bher\b'
   - their system

docs-website/.vale/styles/MyStyle/AvoidThirdPerson.yml

@@ -1,12 +1,11 @@
 extends: substitution
 message: "'%s' is not the correct branding. Use '%s' instead."
 level: error
-ignorecase: true
+ignorecase: false
 swap:
   Deepset: deepset
+  DEEPSET: deepset
   Huggingface: Hugging Face
   huggingface: Hugging Face
   HuggingFace: Hugging Face
-  Haystack: Haystack  # Pass-through to suppress errors from wrong variants
-  haystack: Haystack
-  Deepset Platform: deepset AI Platform
+  HAYSTACK: Haystack

docs-website/.vale/styles/MyStyle/Branding.yml

@@ -1,5 +1,5 @@
 extends: substitution
-message: "Use uppercase for file extensions (e.g., '%s' → '%s')."
+message: "Use uppercase for file extensions: '%s' → '%s'."
 level: warning
 ignorecase: false
 swap:

docs-website/.vale/styles/MyStyle/FileExtensions.yml

@@ -0,0 +1,25 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: warning
+ignorecase: true
+action:
+  name: replace
+swap:
+  drop-down list: list
+  drop-down: list
+  dropdown: list
+  radio button: option
+  radio buttons: options
+  text field: field
+  text fields: fields
+  text area: field
+  hyperlink: link
+  hyperlinks: links
+  pop-up menu: context menu
+  popup menu: context menu
+  push button: button
+  push buttons: buttons
+  list box: list
+  choice box: list
+  pull-down list: list
+  scroll bar: scroll