Introducing “Packages”
Share, sync, and extend Vale-related assets.
The v2.16.0 release of Vale includes a significant, long-awaited feature: the ability to share, sync, and extend Vale configurations across multiple teams and projects.
These shareable configurations, called “packages,” are .zip files that contain a .vale.ini file, a StylesPath folder, or both. You include a package by using the new top-level Packages key in your local .vale.ini file:
StylesPath = .github/styles
MinAlertLevel = suggestionPackages = Microsoft, \
https://github.com/errata-ai/errata.ai/releases/download/v1.0.0/Test.zip[README.md]
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.
An example: Hugo-specific configuration
In order to gain a better understanding of how packages work, we’re going look at an example of the general use case.
Vale’s new website, vale.sh, is a Hugo-generated static site with about 60 Markdown files. We have a basic Vale configuration set up to spell-check our content:
StylesPath = .github/styles
MinAlertLevel = suggestionVocab = Base[*.md]
BasedOnStyles = Vale
When we run Vale with this configuration, we get over 50 errors:
The problem is, though, these aren’t actually errors. Upon closer inspection, we see that the “errors” are all related to the use of Hugo’s shortcodes:
While we could go through and write a few ignore patterns to teach Vale how to handle these snippets, wouldn’t it be nice if we didn’t have to do this for every new Hugo site we work on?
This is where packages come into play. If you head over to vale.sh/hub, you’ll find that there’s already a package created to handle exactly this problem.
All we have to do now is add Packages = Hugo to our .vale.ini file and run the vale sync command:
Now, when we run our same Vale configuration, we’ll see the following:
✔ 0 errors, 0 warnings and 0 suggestions in 62 files.But what happened, exactly? Well, let’s look at our StylesPath:
$ tree -a .github/styles
.github/styles
├── .config
│ └── 0-Hugo.ini
└── Vocab
└── Base
├── accept.txt
└── reject.txt3 directories, 3 files
The packaged Hugo configuration is stored in the new .config folder and loaded before our local .vale.ini file. This allows us to inherit and, if necessary, extend its settings.
We can get a better idea of what’s happening by running vale ls-config:
{
"BlockIgnores": {
"*.md": [
"(?sm)^({{[%\u003c] [^{]*? [%\u003e]}})\\n$",
"(?s) *({{\u003c highlight [^\u003e]* ?\u003e}}.*?{{\u003c ?/ ?highlight \u003e}})"
]
},
"TokenIgnores": {
"*.md": [
"({{[%\u003c] .* [%\u003e]}}.*?{{[%\u003c] ?/.* [%\u003e]}})",
"(\\[.+\\]\\({{\u003c .+ \u003e}}\\))"
]
}
}We now have entries for both BlockIgnores and TokenIgnores coming from the Hugo package. If we want to add our own on top of these, we simply need to update our local .vale.ini file:
StylesPath = .github/styles
MinAlertLevel = suggestionPackages = HugoVocab = Base[*.md]
BasedOnStyles = Vale# Exclude math ($...$) too
TokenIgnores = (\$+[^\n$]+\$+)
If we re-run vale ls-config, we’ll see our new ignore pattern appended to the Hugo ones:
"TokenIgnores": {
"*.md": [
"({{[%\u003c] .* [%\u003e]}}.*?{{[%\u003c] ?/.* [%\u003e]}})",
"(\\[.+\\]\\({{\u003c .+ \u003e}}\\))",
"(\\$+[^\\n$]+\\$+)"
]
}Conclusion
The introduction of packages is a major step forward in improving Vale’s usability across multiple teams and projects.
In the coming weeks, we’re going to continue to expand the new Package Hub with configurations for other static site generators and related tooling to make getting started with Vale much quicker.
If you run into any problems using packages, please open an issue on GitHub.
