Define term lists to further customize styles.
Vocabularies allow you to maintain custom lists of terminology independent of your styles.
StylesPath = "..." # Here's were we define the exceptions to use in *all* # `BasedOnStyles`. Vocab = Some-Name [*] # 'Vale' and 'MyStyle' automatically respects all # custom exceptions. # # The built-in 'Vale' style is required for using # `Vale.Terms`, `Vale.Avoid`, or `Vale.Spelling`. BasedOnStyles = Vale, MyStyle
Vocab is a single folder (stored at
consisting of two plain-text files—
reject.txt—that contain one word, phrase, or regular expression per
The effects of using a custom
Vocab are as follows:
accept.txtare added to every exception list in all styles listed in
BasedOnStyles—meaning that you now only need to update your project’s vocabulary to customize third-party styles (rather than the styles themselves).
accept.txtare automatically added to a substitution rule (
Vale.Terms), ensuring that any occurrences of these words or phrases exactly match their corresponding entry in
reject.txtare automatically added to an existence rule (
Vale.Avoid) that will flag all occurrences as errors.
This means that your exceptions can be developed independent of a style, allowing you to use the same exceptions with multiple styles or switch styles without having to re-implement them.
Vocab entries are stored in
<StylesPath>/Vocab/<name>/ and are then
.vale.ini. For example, consider the following
$ tree styles ├───MyStyle ├───Vocab │ ├───Blog │ └───Marketing └───MyOtherStyle
/styles) contains two styles (
MyOtherStyle) and two vocabularies (
Marketing). You can then
simply reference these entries by their folder name:
StylesPath = styles Vocab = Blog [*] BasedOnStyles = Vale, MyStyle
reject.txt are plain-text files that take one
entry per line:
first [pP]y.*\b third
The entries are case-sensitive (except for rules extending
mentioned above) and may also be regular expressions.
An important factor in successfully implementing a custom
understanding how Vale handles case sensitivity.
While most spell-checking tools ignore case altogether, Vale’s
are case-aware by default. This means that, for example, a vocabulary
will enforce the exact use of “MongoDB”: “mongoDB,” “MongoDb,” etc., will all result in errors. There are two ways around this.
First, you can indicate that a given entry should be case-insensitive by providing an appropriate regular expression:
(?i)MongoDB, marks the entire pattern as case-insensitive while
[Oo]bservability, provides two acceptable options.
Second, you can disable
Vale.Terms and just use
BasedOnStyles = Vale Vale.Terms = NO
This will provide a more traditional spell-checking experience.
Relation to ignore files
The functionality of vocabularies is similar to the existing concept of ignore files.
The major differences are that vocabularies apply to multiple extension points
(rather than just
spelling), support regular expressions, and have built-in
rules associated with them (
In general, this means that ignore files are for style creators while vocabularies are for style users:
If you’re developing or maintaining a style, you may still want to include a custom
MyStyle.Spelling—that packages its own ignore files.
As a user of styles, vocabularies should be able to replace the use of ignore files completely.
For example, if you were using
Vale.Spelling with a
file prior to
v2.3, you can simply copy the contents of
<StylesPath>/Vocab/<MyVocab>/accept.txt and it’ll work the same (you may
also want to disable
Vale.Avoid to replicate the exact