Vocab
Vocabularies (available since v2.3
) allow you to maintain custom lists of
terminology independent of your styles.
Each Vocab
is a single folder (stored at <StylesPath>/Vocab/<name>/
)
consisting of two plain-text files—accept.txt
and
reject.txt
—that contain one word, phrase, or regular expression per
line.
The effects of using a custom Vocab
are as follows:
Entries in
accept.txt
are added to every exception list in all styles listed inBasedOnStyles
—meaning that you now only need to update your project's vocabulary to customize third-party styles (rather than the styles themselves).capitalization
- andconditional
-based rules take the entries as-is (case-sensitive), whilespelling
-based rules are always case-insensitive.Entries in
accept.txt
are automatically added to a substitution rule (Vale.Terms
), ensuring that any occurrences of these words or phrases exactly match their corresponding entry inaccept.txt
.Entries in
reject.txt
are 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.
Folder structure
Vocab
entries are stored in <StylesPath>/Vocab/<name>/
and are then
referenced by <name>
in .vale.ini
. For example, consider the following
folder structure:
Here, our StylesPath
(/styles
) contains two styles (MyStyle
and
MyOtherStyle
) and two vocabularies (Blog
and Marketing
). You can then
simply reference these entries by their folder name:
File format
Both accept.txt
and reject.txt
are plain-text files that take one
entry per line:
The entries are case-sensitive (except for rules extending spelling
, as
mentioned above) and may also be regular expressions.
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 (Vale.Terms
and Vale.Avoid
).
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
spelling
rule—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<StylesPath>/vocab.txt
file prior tov2.3
, you can simply copy the contents ofvocab.txt
into<StylesPath>/Vocab/<MyVocab>/accept.txt
and it'll work the same (you may also want to disableVale.Terms
andVale.Avoid
to replicate the exact experience).