.vale.ini
Learn how to configure Vale for your specific needs.
After installing Vale, you’ll need to create a .vale.ini file in your project’s root directory. This file is used to configure Vale’s behavior and can be used to specify which rules to use, which directories to lint, and more.
The fastest way to get started with Vale is to use the Config Generator to create a .vale.ini configuration file.
Once you have your local .vale.ini created in the directory of your choice, run vale sync from the command line to initialize it:
$ cd some-project
# You'll need to create this file
$ cat .vale.ini
...
$ vale sync
...
$ ls styles
...
$ vale README.mdCheck out our sample repository for a complete example of the required components of a Vale configuration.
Vale’s configuration is read from a .vale.ini file. This file is INI-formatted and consists of multiple sections: core settings, format associations, and format-specific settings:
Core settings appear at the top of the file and apply to the application itself rather than a specific file format.
Format associations allow you to associate an “unknown” file extension with a supported one:
In the example above, we’re telling Vale to treat MDX files as Markdown files. Note that this is merely an extension-level substitution and is not a means of adding support for a new file type.
Format-specific sections apply their settings only to files that match their associated glob pattern. For example, [*] matches all files while [*.{md,txt}] only matches files that end with either .md or .txt.
You can have as many format-specific sections as you’d like and settings defined under a more specific section will override those in [*].
See Globbing for more information on how to use glob patterns with Vale.
Heads up!
You can override the default search process by manually specifying a path using the --config option or by defining a VALE_CONFIG_PATH environment variable.
Vale expects its configuration to be in a file named .vale.ini or _vale.ini. It’ll start looking for this file in the directory that the vale command was run from and then search up the file tree until it finds one.
If no ancestor of the current directory has a configuration file, Vale will use a global configuration file (see below).
In addition to project-specific configurations, Vale also supports a global configuration file. The expected location of the global configuration depends on your operating system:
Windows
%LOCALAPPDATA%\vale\.vale.ini
macOS
$HOME/Library/Application Support/vale/.vale.ini
Unix
$XDG_CONFIG_HOME/vale/.vale.ini
(Run the vale ls-dirs command to see the exact locations on your system.)
This is different from the other config-defining options (--config, VALE_CONFIG_PATH, etc.) in that it’s loaded in addition to, rather than instead of, any other configuration sources.
In other words, this config file is always loaded and is read after any other sources to allow for project-agnostic customization.
Vale’s configuration system supports using multiple configuration files at the same time. Typically, this is done in cases where you are contributing to a project that already has an established configuration but you want to make local changes.
For example, let’s say you’re working on a project that uses the following configuration:
Now, let’s say you want to add the write-good style to your local configuration.
Create a global configuration file—for macOS, this would be ~/Library/Application Support/vale/.vale.ini (see above for other OSes).
Now, when you run Vale, it will show results from both the ProjectStyle and write-good styles locally.
You’ll notice that multi-valued settings (like BasedOnStyles) are merged together, while single-valued settings (like MinAlertLevel) are overridden.
This allows you to contribute to projects with established styles while still being able to make local changes.