You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
[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.
4
+
5
+
It applies in the following contexts:
6
+
7
+
***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).
8
+
***Local**: Install Vale for immediate, offline feedback in VS Code while editing. Shows all levels: suggestions, warnings, and errors.
9
+
10
+
Need to install Vale? See [SETUP.md](/.vale/SETUP.md) for installation steps.
11
+
12
+
## File Structure
13
+
14
+
```
15
+
.vale.ini # Main configuration
16
+
.vale/
17
+
styles/
18
+
Microsoft/ # Synced from vale.sh (gitignored)
19
+
Mendix/ # Custom rules (committed to Git)
20
+
*.yml # Mendix-specific style rules
21
+
RULES.md # Complete list of Mendix custom rules and overrides
22
+
README.md # Rule documentation
23
+
```
24
+
25
+
## What the Rules Check
26
+
27
+
Vale is configured to enforce both general writing best practices and Mendix-specific standards:
28
+
29
+
***Microsoft Style Guide rules**: Grammar, punctuation, readability, inclusive language, and general technical writing conventions
30
+
***Mendix custom rules**: Product terminology, capitalization standards, forbidden phrases, link formatting, and documentation-specific patterns
31
+
32
+
Rules are categorized by severity:
33
+
***Suggestions**: Recommendations that improve clarity but aren't mandatory
34
+
***Warnings**: Style violations that should be fixed before merging
35
+
***Errors**: Critical issues that must be resolved
36
+
37
+
Each rule uses an `action` type to define what it checks:
38
+
39
+
*`suggest`: Offers alternative phrasing or improvements
40
+
*`replace`: Identifies text to replace with specific alternatives
41
+
*`remove`: Flags text to delete (for example, redundant words)
42
+
*`existence`: Detects the presence of forbidden patterns or phrases
43
+
*`substitution`: Finds patterns and suggests substitutions
44
+
*`occurrence`: Checks for repeated or missing patterns
45
+
*`conditional`: Applies rules based on context
46
+
47
+
For a complete list of custom Mendix rules and overrides, see [Custom Mendix Rules](/.vale/styles/Mendix/RULES.md).
Vale is configured but not yet installed. This guide walks you through setup.
4
+
5
+
## Why Install Locally?
6
+
7
+
***Immediate feedback** - See violations as you write, not after pushing
8
+
***Faster iteration** - Fix issues before creating a PR
9
+
***More feedback** - See suggestions and warnings locally; the GitHub Action is configured to only show errors
10
+
11
+
**Note:** Even without local installation, your PRs will be checked automatically by a GitHub Action: [.github/workflows/vale.yml](../.github/workflows/vale.yml).
12
+
13
+
## Installation (Choose One)
14
+
15
+
### For macOS
16
+
17
+
1. Download [Homebrew](https://brew.sh/) if you don't already have it.
18
+
2. In your terminal, run the following command:
19
+
20
+
```bash
21
+
brew install vale
22
+
```
23
+
24
+
### For Windows
25
+
26
+
1. On https://github.com/vale-cli/vale/releases, download the Windows version from Assets
27
+
2. Right-click the zip file and select **Extract All**
28
+
3. Open PowerShell and run:
29
+
30
+
```powershell
31
+
# Create a bin directory for your tools
32
+
mkdir $HOME\bin -Force
33
+
34
+
# Move vale.exe there (adjust the path if you extracted it elsewhere)
Switch to the docs directory (`cd docs`), then run:
55
+
56
+
```bash
57
+
vale sync
58
+
```
59
+
60
+
This downloads Microsoft's style pack to `.vale/styles/Microsoft/`.
61
+
62
+
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).
63
+
64
+
3.**Install VS Code extension:**
65
+
- Install the [Vale VS Code extension](https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode).
66
+
- Restart VS Code.
67
+
- Open any `.md` file in `content/en/docs/`.
68
+
- Violations show as squiggly underlines in the file and appear in the **Problems** tab in the bottom pane.
69
+
- 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.
70
+
- Save changes to rerun the linter.
71
+
- If desired, you can adjust the extension's settings in VS Code to show a different minimum alert level. For example, if you set `minAlertLevel` to `warning`, it will only report warnings and errors, not suggestions.
72
+
73
+
4.**If you have open PRs:** Merge `development` into your branch to get the Vale configuration files.
0 commit comments