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