.vale.ini
Learn how to configure Vale for your specific needs.
Creating a .vale.ini File
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.
File structure
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
Core settings appear at the top of the file and apply to the application itself rather than a specific file format.
Format associations
Format associations allow you to associate an “unknown” file extension with a supported one:
In the example above, we’re telling Vale to treat .txt 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.
An association changes how Vale reads a file, not what it’s called. Sections still match the name on disk, so the example above needs a [*.txt] section—[*.md] won’t reach those files:
Format-specific settings
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 [*].
A pattern can name a path as well as an extension, so [docs/src/*.md] narrows a section to one part of the project:
A path pattern is matched against the file as Vale was asked for it, so write it relative to where you run Vale. The section above applies to vale ., vale docs, and vale docs/src/page.md run from the project root; it doesn’t match an absolute path such as vale /home/me/project/docs/src/page.md.
See Globbing for more information on how to use glob patterns with Vale.
Search process
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).
Global configuration
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.
Cascading overrides
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.
Last updated