Add Vale – preliminary styles and github action

.github/workflows/vale.yml

@@ -0,0 +1,23 @@
+name: Vale style check
+on: 
+  pull_request:
+    paths:
+      - '**.mdx'
+      - '**.md'
+      - '.vale/**'
+      - '.vale.ini'
+
+jobs:
+  vale:
+    runs-on: ubuntu-latest
+    if: |
+      github.event.pull_request.user.login != 'fern-support' &&
+      github.event.pull_request.user.login != 'github-actions'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: errata-ai/vale-action@reviewdog
+        with:
+          files: fern
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

.vale.ini

@@ -0,0 +1,17 @@
+StylesPath = .vale/styles
+
+MinAlertLevel = suggestion
+
+Packages = Microsoft
+
+[formats]
+mdx = md
+
+[*.mdx]
+BasedOnStyles = Microsoft, FernStyles
+
+# Disable specific rules
+Microsoft.GenderBias = NO # Not relevant for technical documentation
+Microsoft.Acronyms = NO # Handled in FernStyles
+Microsoft.Vocab = NO # Too granular for now
+

.vale/styles/FernStyles/Acronyms.yml

@@ -0,0 +1,65 @@
+extends: conditional
+message: "'%s' has no definition."
+link: https://docs.microsoft.com/en-us/style-guide/acronyms
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP
+  - MDX # Fern-specific

.vale/styles/FernStyles/Please.yml

@@ -0,0 +1,6 @@
+extends: existence
+message: "Avoid using '%s' in technical documentation."
+level: warning
+ignorecase: true
+tokens:
+  - please # Instead of "Please refer to the documentation", say "Refer to the documentation"

.vale/styles/FernStyles/Reject.yml

@@ -0,0 +1,8 @@
+extends: substitution
+message: "Use '%s' instead of '%s'."
+level: error
+ignorecase: true
+swap:
+  whitelist: allowlist
+  blacklist: denylist
+  Visual Editor: Fern Editor

.vale/styles/Microsoft/AMPM.yml

@@ -0,0 +1,9 @@
+extends: existence
+message: Use 'AM' or 'PM' (preceded by a space).
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/date-time-terms
+level: error
+nonword: true
+tokens:
+  - '\d{1,2}[AP]M'
+  - '\d{1,2} ?[ap]m'
+  - '\d{1,2} ?[aApP]\.[mM]\.'

.vale/styles/Microsoft/Accessibility.yml

@@ -0,0 +1,30 @@
+extends: existence
+message: "Don't use language (such as '%s') that defines people by their disability."
+link: https://docs.microsoft.com/en-us/style-guide/a-z-word-list-term-collections/term-collections/accessibility-terms
+level: suggestion
+ignorecase: true
+tokens:
+  - a victim of
+  - able-bodied
+  - an epileptic
+  - birth defect
+  - crippled
+  - differently abled
+  - disabled
+  - dumb
+  - handicapped
+  - handicaps
+  - healthy person
+  - hearing-impaired
+  - lame
+  - maimed
+  - mentally handicapped
+  - missing a limb
+  - mute
+  - non-verbal
+  - normal person
+  - sight-impaired
+  - slow learner
+  - stricken with
+  - suffers from
+  - vision-impaired

.vale/styles/Microsoft/Acronyms.yml

@@ -0,0 +1,64 @@
+extends: conditional
+message: "'%s' has no definition."
+link: https://docs.microsoft.com/en-us/style-guide/acronyms
+level: suggestion
+ignorecase: false
+# Ensures that the existence of 'first' implies the existence of 'second'.
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Z][a-z]+ )+\(([A-Z]{3,5})\)'
+# ... with the exception of these:
+exceptions:
+  - API
+  - ASP
+  - CLI
+  - CPU
+  - CSS
+  - CSV
+  - DEBUG
+  - DOM
+  - DPI
+  - FAQ
+  - GCC
+  - GDB
+  - GET
+  - GPU
+  - GTK
+  - GUI
+  - HTML
+  - HTTP
+  - HTTPS
+  - IDE
+  - JAR
+  - JSON
+  - JSX
+  - LESS
+  - LLDB
+  - NET
+  - NOTE
+  - NVDA
+  - OSS
+  - PATH
+  - PDF
+  - PHP
+  - POST
+  - RAM
+  - REPL
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP