A Vale-compatible implementation of the Microsoft Writing Style Guide.
111
stars
198
commits
Go
primary language
Aug 26, 2026
updated
README
Microsoft
NOTE: This project is neither maintained nor endorsed by Microsoft.
This repository contains a Vale-compatible implementation of the Microsoft Writing Style Guide (LICENSE).
Getting started
To get started, add the package to your configuration file (as shown below) and then run vale sync.
StylesPath = styles
MinAlertLevel = suggestion
Packages = Microsoft
[*]
BasedOnStyles = Vale, Microsoft
See Packages for more information.
Repository structure
/Microsoft- The YAML-based rule implementations that make up our style.
/fixtures- The individual unit tests. Each directory should be named after a rule found in
/Microsoftand include its own.vale.inifile that isolates its target rule. /testdata- The expected Vale output for each fixture directory, one
<Rule>.ctfile per fixture. We use go-cmdtest to run Vale against each fixture and compare its output. Run the suite withgo test ./...; regenerate the expectations after an intentional change withgo test ./... -update. /coverage- How much of the style guide we implement, tracked topic by topic. Each file mirrors one top-level section of the guide, and each key is a subtopic set to
trueorfalse, optionally followed by a comment naming the rules that implement it.
Coverage
Run go test -v -run TestCoverage ./... to print the current figures:
guidelines: 37/64 (57.8%)
A-Z word list: 106/849 (12.5%)
The two are reported separately because the A–Z word list is roughly ten times the size of everything else, so a single combined percentage tells you almost nothing about the guidelines.
The same test enforces what keeps the number honest: values must be exactly
true or false, and every rule named in a comment must still exist. A rule
that's renamed or merged away therefore can't leave a topic silently claiming
coverage it no longer has.
Sections of the guide that describe process rather than prose have no manifest,
since there's nothing there for a linter to check: Checklists, Content planning,
Design planning, Final publishing review, Search and writing, and Top 10 tips.
Scannable content and Text formatting are also absent for now; their
lintable subtopics (headings, sentence-style capitalization) are already counted
under capitalization.yml, and listing them again would double-count.
Extension points
Similar repos
Languages
Go
100.0%
A Vale-compatible implementation of the Microsoft Writing Style Guide.
111
stars
198
commits
Go
primary language
Aug 26, 2026
updated
README
Microsoft
NOTE: This project is neither maintained nor endorsed by Microsoft.
This repository contains a Vale-compatible implementation of the Microsoft Writing Style Guide (LICENSE).
Getting started
To get started, add the package to your configuration file (as shown below) and then run vale sync.
StylesPath = styles
MinAlertLevel = suggestion
Packages = Microsoft
[*]
BasedOnStyles = Vale, Microsoft
See Packages for more information.
Repository structure
/Microsoft- The YAML-based rule implementations that make up our style.
/fixtures- The individual unit tests. Each directory should be named after a rule found in
/Microsoftand include its own.vale.inifile that isolates its target rule. /testdata- The expected Vale output for each fixture directory, one
<Rule>.ctfile per fixture. We use go-cmdtest to run Vale against each fixture and compare its output. Run the suite withgo test ./...; regenerate the expectations after an intentional change withgo test ./... -update. /coverage- How much of the style guide we implement, tracked topic by topic. Each file mirrors one top-level section of the guide, and each key is a subtopic set to
trueorfalse, optionally followed by a comment naming the rules that implement it.
Coverage
Run go test -v -run TestCoverage ./... to print the current figures:
guidelines: 37/64 (57.8%)
A-Z word list: 106/849 (12.5%)
The two are reported separately because the A–Z word list is roughly ten times the size of everything else, so a single combined percentage tells you almost nothing about the guidelines.
The same test enforces what keeps the number honest: values must be exactly
true or false, and every rule named in a comment must still exist. A rule
that's renamed or merged away therefore can't leave a topic silently claiming
coverage it no longer has.
Sections of the guide that describe process rather than prose have no manifest,
since there's nothing there for a linter to check: Checklists, Content planning,
Design planning, Final publishing review, Search and writing, and Top 10 tips.
Scannable content and Text formatting are also absent for now; their
lintable subtopics (headings, sentence-style capitalization) are already counted
under capitalization.yml, and listing them again would double-count.
Extension points
Similar repos
Languages
Go
100.0%