Add Vale

.github/workflows/vale.yml

@@ -0,0 +1,35 @@
+name: Vale Linting
+
+# Trigger on PRs that change Markdown files
+on:
+  pull_request:
+    paths:
+      - 'content/en/docs/**/*.md'
+
+# Allow reading repo contents and posting PR comments
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  vale:
+    # Only run on Mendix repo, not forks, and not on draft PRs
+    if: github.repository_owner == 'mendix' && github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    # Cancel old runs when new commits are pushed
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.event.pull_request.number }}
+      cancel-in-progress: true
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Run Vale
+        uses: vale-cli/vale-action@v2
+        with:
+          files: '.'  # Check all changed files in the PR
+          version: 3.14.2
+          fail_on_error: false
+          reporter: github-pr-review
+          vale_flags: '--minAlertLevel=error'  # Only flag errors, not warnings or suggestions
+          filter_mode: diff_context  # Only check around changed lines, not entire files

.gitignore

@@ -9,6 +9,7 @@ hugo.exe
 /.claude/audit.log
 /.claude/settings.local.json
 /.mcp.json
+/.vale/styles/Microsoft/
 
 # For Mac users
 .DS_Store

.vale.ini

@@ -0,0 +1,98 @@
+# Vale configuration for Mendix documentation
+# See: https://vale.sh/docs/topics/config/
+
+StylesPath = .vale/styles
+MinAlertLevel = suggestion
+
+# Packages to sync from vale.sh
+# Microsoft = Microsoft Writing Style Guide
+Packages = Microsoft
+
+# Ignore patterns
+[*.{md,mdx}]
+# Ignore code blocks
+BlockIgnores = (?s) *```(?:[\w\{\}]+)?$(.+?)^ *```
+# Ignore front matter (YAML blocks at start of file), anchor IDs in headings, and Hugo shortcodes
+# Rules can use explicit scope lists (paragraph, heading, list, table, blockquote) to exclude this content
+TokenIgnores = (\A---\s*\n(.|\n)+?\n---\s*\n), (\{#[^\}]+\}), (\{\{[^\}]+\}\})
+
+# Markdown files use both Microsoft and custom Mendix styles
+BasedOnStyles = Microsoft, Mendix
+
+# ============================================================================
+# Microsoft Style Guide Rule Overrides
+# ============================================================================
+# The following rules are disabled or adjusted to align with Mendix style guide
+# requirements documented in content/en/docs/community-tools/contribute-to-mendix-docs/style-guide/
+
+# Acronyms
+# Microsoft requires title case for acronym definitions; Mendix allows sentence case too
+# Replacement: Mendix.Acronyms accepts sentence-case definitions
+Microsoft.Acronyms = NO
+
+# Contractions
+# Microsoft requires contractions; Mendix prohibits them
+# Mendix style guide: "Do not use contractions. Write 'it is' and not 'it's.'"
+Microsoft.Contractions = NO
+
+# Dashes
+# Microsoft removes all spaces around em/en dashes; Mendix has context-specific rules
+# Mendix style guide: Em dashes (—) have no spaces; en dashes (–) have spaces except in number ranges
+# Replacement: Mendix.Dashes enforces en dash spacing in number ranges and between words
+#             Mendix.ListIntroductions enforces en dashes (not em dashes) for list item introductions
+Microsoft.Dashes = NO
+
+# Foreign
+# Microsoft's i.e./e.g. replacements remove spacing incorrectly when applied as quick fixes
+# Replacement: Mendix.Foreign provides correct spacing and punctuation in replacements
+Microsoft.Foreign = NO
+
+# General URL
+# Microsoft prefers "address" over "URL"; Mendix does not
+Microsoft.GeneralURL = NO
+
+# Heading Acronyms
+# Microsoft prohibits acronyms in headings; Mendix does not
+Microsoft.HeadingAcronyms = NO
+
+# Heading Capitalization
+# Microsoft suggests sentence-style; Mendix requires title case
+# Mendix style guide: "Use title case for titles and headings"
+# Replacement: Mendix.HeadingTitleCase enforces title case capitalization
+Microsoft.Headings = NO
+
+# Heading Punctuation
+# Microsoft prohibits all end punctuation; Mendix allows question marks
+# Replacement: Mendix.HeadingPunctuation prohibits periods, exclamation marks, and colons but allows question marks
+Microsoft.HeadingPunctuation = NO
+
+# Passive
+# Too many that don't need changes
+Microsoft.Passive = NO
+
+# Spacing
+# Technical content like **StationConnector.Administrator** triggers false positives
+Microsoft.Spacing = NO
+
+# Terms
+# Too far off from Mendix terminology guidance
+Microsoft.Terms = NO
+
+# Vocab
+# Too far off from Mendix terminology guidance
+Microsoft.Vocab = NO
+
+# ============================================================================
+# Path-Specific Overrides
+# ============================================================================
+
+# First-Person Plural
+# Release notes allow first-person plural "we"
+[content/en/docs/releasenotes/*.md]
+Microsoft.We = NO
+
+# Product Names
+# Disable deprecated product name checks in historical documentation
+# These versions used older terminology that may have been accurate at the time
+[content/en/docs/{refguide8,refguide9,refguide10,howto8,howto9,howto10,releasenotes}/**/*.md]
+Mendix.ProductNames = NO

.vale/README.md

@@ -0,0 +1,54 @@
+# Vale Configuration for Mendix Documentation
+
+[Vale](https://vale.sh/docs/) lints the documentation with both Microsoft Writing Style Guide rules and custom Mendix rules to catch style violations, grammar issues, and terminology inconsistencies. It matches text against patterns and rules defined in the .vale/styles YAML files, providing deterministic feedback based on these configurable rules.
+
+It applies in the following contexts:
+
+* **GitHub PRs**: Runs automatically on PRs marked "Ready for review" and posts inline comments on changed lines. Only shows errors (warnings and suggestions are hidden).
+* **Local**: Install Vale for immediate, offline feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors.
+
+Need to install Vale? See [SETUP.md](/.vale/SETUP.md) for installation steps.
+
+## File Structure
+
+```
+.vale.ini                      # Main configuration
+.vale/
+  styles/
+    Microsoft/                 # Synced from vale.sh (gitignored)
+    Mendix/                    # Custom rules (committed to Git)
+      *.yml                    # Mendix-specific style rules
+      RULES.md                 # Complete list of Mendix custom rules and overrides
+  README.md                    # Rule documentation
+```
+
+## What the Rules Check
+
+Vale is configured to enforce both general writing best practices and Mendix-specific standards:
+
+* **Microsoft Style Guide rules**: Grammar, punctuation, readability, inclusive language, and general technical writing conventions
+* **Mendix custom rules**: Product terminology, capitalization standards, forbidden phrases, link formatting, and documentation-specific patterns
+
+Rules are categorized by severity:
+* **Suggestions**: Recommendations that improve clarity but aren't mandatory
+* **Warnings**: Style violations that should be fixed before merging
+* **Errors**: Critical issues that must be resolved
+
+Each rule uses an `action` type to define what it checks:
+
+* `suggest`: Offers alternative phrasing or improvements
+* `replace`: Identifies text to replace with specific alternatives
+* `remove`: Flags text to delete (for example, redundant words)
+* `existence`: Detects the presence of forbidden patterns or phrases
+* `substitution`: Finds patterns and suggests substitutions
+* `occurrence`: Checks for repeated or missing patterns
+* `conditional`: Applies rules based on context
+
+For a complete list of custom Mendix rules and overrides, see [Custom Mendix Rules](/.vale/styles/Mendix/RULES.md).
+
+## Read More
+
+* [Vale Documentation](https://vale.sh/docs/)
+* [Microsoft Style Guide Package](https://github.com/errata-ai/Microsoft)
+* [Vale Rule Syntax](https://vale.sh/docs/topics/styles/)
+* [Custom Mendix Rules](/.vale/styles/Mendix/RULES.md)

.vale/SETUP.md

@@ -0,0 +1,72 @@
+# Vale Setup Guide
+
+Vale is configured but not yet installed. This guide walks you through setup.
+
+## Why Install Locally?
+
+* **Immediate feedback** - See violations as you write, not after pushing
+* **Faster iteration** - Fix issues before creating a PR
+* **More feedback** - See suggestions and warnings locally; the GitHub Action is configured to only show errors
+
+**Note:** Even without local installation, your PRs will be checked automatically by a GitHub Action: [.github/workflows/vale.yml](../.github/workflows/vale.yml).
+
+## Installation (Choose One)
+
+### For macOS
+
+1. Download [Homebrew](https://brew.sh/) if you don't already have it.
+2. In your terminal, run the following command:
+
+   ```bash
+   brew install vale
+   ```
+
+### For Windows
+
+1. On https://github.com/vale-cli/vale/releases, download the Windows version from Assets
+2. Right-click the zip file and select **Extract All**
+3. Open PowerShell and run:
+
+   ```powershell
+   # Create a bin directory for your tools
+   mkdir $HOME\bin -Force
+
+   # Move vale.exe there (adjust the path if you extracted it elsewhere)
+   Move-Item $HOME\Downloads\vale_*_Windows_64-bit\vale.exe $HOME\bin\
+
+   # Add to PATH
+   $currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
+   [Environment]::SetEnvironmentVariable("Path", "$currentPath;$HOME\bin", "User")
+   ```
+
+## Post-Installation
+
+After installing Vale:
+
+1. **Verify the installation worked:**
+
+   ```bash
+   vale --version
+   ```
+
+2. **Sync the Microsoft Style Guide rules:**
+
+   Switch to the docs directory (`cd docs`), then run:
+
+   ```bash
+   vale sync
+   ```
+
+   This downloads Microsoft's style pack to `.vale/styles/Microsoft/`.
+
+   If you get a `Runtime error: No sources provided` error, verify that there is a `.vale.ini` file in the root of the docs repository (and that you are also in the root of the docs repository).
+
+3. **Install VS Code extension:**
+   - Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode).
+   - Restart VS Code.
+   - Open any `.md` file in `content/en/docs/`.
+   - Violations show as squiggly underlines in the file and appear in the **Problems** tab in the bottom pane.
+   - Many Vale rules support automatic fixes—hover over an underlined issue and click **Quick Fix** or click the lightbulb icon next to flagged text in the **Problems** tab.
+   - Save changes to rerun the linter.
+
+4. **If you have open PRs:** Merge `development` into your branch to get the Vale configuration files.

.vale/styles/Mendix/Acronyms.yml

@@ -0,0 +1,73 @@
+extends: conditional
+message: "Define '%s' on first use."
+link: https://docs.mendix.com/community-tools/contribute-to-mendix-docs/style-guide/grammar-formatting/#acronyms-and-initialisms
+level: suggestion
+ignorecase: false
+scope:
+  - paragraph
+  - heading
+  - list
+  - table
+  - blockquote
+# Ensures that the existence of 'first' implies the existence of 'second'.
+# Modified from Microsoft.Acronyms to accept sentence-case definitions
+# e.g., "personal access token (PAT)" not just "Personal Access Token (PAT)"
+first: '\b([A-Z]{3,5})\b'
+second: '(?:\b[A-Za-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
+  - REST
+  - RSA
+  - SCM
+  - SCSS
+  - SDK
+  - SQL
+  - SSH
+  - SSL
+  - SVG
+  - TBD
+  - TCP
+  - TODO
+  - URI
+  - URL
+  - USB
+  - UTF
+  - XML
+  - XSS
+  - YAML
+  - ZIP

.vale/styles/Mendix/AmericanSpelling.yml

@@ -0,0 +1,47 @@
+extends: substitution
+message: "Use American English spelling '%s' instead of '%s'."
+link: https://learn.microsoft.com/en-us/style-guide/word-choice/use-us-spelling-avoid-non-english-words
+ignorecase: true
+level: error
+nonword: false
+# Exclude code, comments, and raw content (front matter, shortcodes, anchor IDs)
+scope: text
+action:
+  name: replace
+swap:
+  # -ise/-ize patterns
+  '\b(organ|real|recogn|standard|normal|legal|special|general|minim|maxim|optim|neutral|central|character|categor|formal|final|visual|modern|popular|personal|national|local|global|digital|custom|util|mobil|stabil|prior|anal|summar|critic|emphas|synchron)ise([ds])?\b': '$1ize$2'
+
+  # -our/-or patterns
+  '\b(col|behavi|fav|neighb|lab|hon|hum|sav|harb)our([s]?)\b': '$1or$2'
+
+  # -re/-er patterns
+  '\bcentre([ds])?\b': 'center$1'
+  '\btheatre([ds])?\b': 'theater$1'
+
+  # -ence/-ense patterns
+  '\bdefence([s]?)\b': 'defense$1'
+  '\blicence([s]?)\b': 'license$1'
+  '\boffence([s]?)\b': 'offense$1'
+  '\bpretence([s]?)\b': 'pretense$1'
+
+  # -logue/-log patterns
+  '\bcatalogue([ds])?\b': 'catalog$1'
+  '\bdialogue([ds])?\b': 'dialog$1'
+
+  # Double-L patterns
+  '\bcancell(ed|ing)\b': 'cancel$1'
+  '\btravell(ed|ing|er)\b': 'travel$1'
+  '\bmodell(ed|ing)\b': 'model$1'
+
+  # Common individual words
+  '\bgrey\b': 'gray'
+  '\bwhilst\b': 'while'
+  '\bamongst\b': 'among'
+  '\btowards\b': 'toward'
+  '\bafterwards\b': 'afterward'
+  '\bbackwards\b': 'backward'
+  '\bforwards\b': 'forward'
+  '\bupwards\b': 'upward'
+  '\bdownwards\b': 'downward'
+  '\bprogramme([ds])?\b': 'program$1'