Published in


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 = suggestion
Packages = Microsoft, \
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,, 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 = suggestion
Vocab = Base[*.md]
BasedOnStyles = Vale

When we run Vale with this configuration, we get over 50 errors:

Example Vale output

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:

Shortcode-related spelling errors

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, 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:

Output of 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
├── .config
│ └── 0-Hugo.ini
└── Vocab
└── Base
├── accept.txt
└── reject.txt
3 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 = suggestion
Packages = 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}}\\))",


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.




Weekly tips, tricks, and updates about the Vale linter and its ecosystem of software.

Recommended from Medium

Recap of AWS re: Invent 18 — State of the cloud

How to Setup a Virtual Environment for Python Development

The 5 Misconceptions of Sponsoring a Virtual Conference

I am Fluttered

12. My Conference Is Bigger Than Your Conference

Which IDE Is For Me?

Innovation As a Team Sport: PhraseApp’s August HackDay

Update on SolRazr’s IDO

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Joseph Kato

Joseph Kato

An open-source software developer with interests in natural language processing, data science, and collaborative writing. More @

More from Medium

Meteor Social Login with GitHub

AWS CDK And TS — The Basic

How To Make Your Number Pad Useful | PLUGHITZ Live

Dev Spotlight: Decagon Trainee Builds All-in-One Expense Tracking App