Share, sync, extend, and update Vale-related assets.


Packages provide a means of sharing, extending, syncing, and updating Vale configurations.

graph TD C{Package} C --> D[Project 1] C --> E[Project 2] C --> F[Project 3] F --> |local overrides| G[Project 3]

In the example above, Project 1 and 2 will have identical configurations (as inherited from the upstream package). Any changes to the upstream package will propagate to both projects.

Project 3 starts with the same configuration as 1 and 2, but applies its own overrides through a local .vale.ini file—for example, maybe you want to disable a rule or change a rule’s severity.

Structure and Hosting

A package is a .zip file that contains a .vale.ini file, a StylesPath folder, or both. You include a package by using the top-level Packages key in your local .vale.ini file:

StylesPath = .github/styles
MinAlertLevel = suggestion

Packages = Microsoft, \

BasedOnStyles = Vale

The Packages key accepts two types of values: (1) a name of a package hosted in the official Package Hub or (2) a URL to an externally-hosted package.


Style-only (such as write-good) packages are a .zip archive of a single style folder:

$ unzip
   creating: write-good/
  inflating: write-good/
  inflating: write-good/Cliches.yml
  inflating: write-good/ThereIs.yml
  inflating: write-good/Weasel.yml
  inflating: write-good/TooWordy.yml
  inflating: write-good/Passive.yml
  inflating: write-good/So.yml
  inflating: write-good/Illusions.yml
  inflating: write-good/E-Prime.yml
  inflating: write-good/meta.json

After running the sync command, the style will be added to the active StylesPath.


Config-only (such as Hugo) packages are a .zip archive of a single .vale.ini file:

$ unzip
   creating: Hugo/
  inflating: Hugo/.vale.ini

After running the sync command, the configuration file be added to StylesPath/.config according to the order in which it was loaded.


Complete packages contain both a .vale.ini file and an associated StylesPath folder.

The StylesPath should be named “styles” and can contain any typically-supported subfolder—such as styles and vocabularies. The .vale.ini file should reference the included StylesPath:

# This is subfolder included in our .zip archive.
StylesPath = styles

# Complete packages can include other, externally-defined
# packages.
Packages = proselint

# Normal configuration ...
Test.Rule = YES

The packaged StylesPath will be merged with the active local StylesPath and any included configuration files will be added to the local StylesPath/.config folder.

Packages and VCS

You’ll want to add any packaged configuration components to your .gitignore (or equivalent) file.

While this can be as simple as ignoring your entire StylesPath, it’s likely that you’ll also have some local components as well.

# We want to ignore our StylesPath *except* for our local
# `Vocab/Base` folder.


The above example ignores the entire .github/styles/ folder except for .github/styles/Vocab/Base (which we want to track changes for).