Packages

Learn about Vale's configuration distribution system.

Packages = Google, write-good

[*.md]
BasedOnStyles = Vale, Google, write-good

Packages provide a means of sharing, extending, syncing, and updating Vale configurations.

One upstream package is inherited by several projects, so an upstream change reaches all of them. Within a project, configuration is layered: the first package is overridden by the second, and local configuration overrides both.

In the example above, projects 1 and 2 will have identical configurations (as inherited from the upstream package). Any changes to the upstream package will propagate to both projects.

Structure and hosting

A package is a .zip file that contains a .vale.ini file, a StylesPath folder, or both. You include a package by using the top-level Packages key in your local .vale.ini file:

StylesPath = .github/styles
MinAlertLevel = suggestion

Packages = Microsoft, https://github.com/vale-cli/write-good/releases/download/v0.4.0/write-good.zip

[README.md]
BasedOnStyles = Vale

1

Package types — four accepted values

The Packages key accepts four types of values:

• A name of a package hosted in the official Package Explorer;
• a URL to an externally-hosted package;
• an absolute or relative path to a .zip file located in the local file system; or
• an absolute or relative path to a directory containing package files.

2

Style-only

Style-only (such as write-good) packages are a .zip archive of a single style folder:

$ unzip write-good.zip
Archive:  write-good.zip
   creating: write-good/
  inflating: write-good/README.md
  inflating: write-good/Cliches.yml
  inflating: write-good/ThereIs.yml
  inflating: write-good/Weasel.yml
  inflating: write-good/TooWordy.yml
  inflating: write-good/Passive.yml
  inflating: write-good/So.yml
  inflating: write-good/Illusions.yml
  inflating: write-good/E-Prime.yml
  inflating: write-good/meta.json

After running the sync command, the style will be added to the active StylesPath.

3

Config-only

Config-only (such as Hugo) packages are a .zip archive of a single .vale.ini file:

$ unzip Hugo.zip
Archive:  Hugo.zip
   creating: Hugo/
  inflating: Hugo/.vale.ini

After running the sync command, the configuration file will be added to StylesPath/.vale-config according to the order in which it was loaded.

4

Complete

Complete packages contain both a .vale.ini file and an associated StylesPath folder:

$ tree MyPackage
MyPackage
├── .vale.ini
└── styles
    ├── MyStyle
    │   └── MyRule.yml
    └── config
        ├── dictionaries
        │   └── MyDic.dic
        ├── scripts
        │   └── MyScript.tengo
        └── vocabularies
            └── MyVocab
                ├── accept.txt
                └── reject.txt

The StylesPath should be named “styles” and can contain any typically-supported subfolder—such as styles and vocabularies. The .vale.ini file should reference the included StylesPath:

# This is subfolder included in our .zip archive.
StylesPath = styles

# Complete packages can include other, externally-defined
# packages.
Packages = proselint

# Normal configuration ...
[*.{md,adoc}]
Test.Rule = YES

The packaged StylesPath will be merged with the active local StylesPath and any included configuration files will be added to the local StylesPath/.vale-config folder.

Pinning a version

Naming a package installs its latest release, so the rules it brings can change as the package is updated. To hold a package at a known version, give the release URL in place of the name:

StylesPath = styles

Packages = https://github.com/vale-cli/Google/releases/download/v0.7.0/Google.zip

[*.md]
BasedOnStyles = Google

A style takes its name from the folder inside the archive, so BasedOnStyles reads the same either way — only where the package comes from changes. Run sync again after editing the URL to move to a different version.

This is worth doing wherever a new rule arriving on its own would be disruptive, such as a repository several people write in, or a CI job that fails on new alerts.

Ordering

In the case of conflicting configuration, the order in which packages are loaded is important:

Packages = pkg1, pkg2

# Local configuration ...
[*.{md,adoc}]
Test.Rule = YES

In the above example, pkg2 will override any conflicting configuration from pkg1. Similarly, local configuration will override any conflicting package.

VCS

You’ll want to add any packaged configuration components to your .gitignore (or equivalent) file.

While this can be as simple as ignoring your entire StylesPath, it’s likely that you’ll also have some local components as well.

# We want to ignore our StylesPath *except* for our local
# `vocabularies/Base` directory.

.github/styles/*
!.github/styles/config/

.github/styles/config/*
!.github/styles/config/vocabularies/

.github/styles/config/vocabularies/*
!.github/styles/config/vocabularies/Base

The above example ignores the entire .github/styles/ folder except for .github/styles/config/vocabularies/Base (which we want to track changes for).