Defame1297
ca744d5d6c
Gotcha 1 said a style in BasedOnStyles that is not built-in and not already under StylesPath "finds nothing until vale sync fetches it — a clean run is not proof anything linted". Reproduced against vale 3.15.2: that case is a hard `E100 [loadStyles] style '<name>' does not exist on StylesPath`, exit 2. Nothing is linted and nothing is silent. Worse, the same commit deleted the Gotcha that was the actual diagnostic — that Packages and BasedOnStyles are separate keys and a style lints only once it is in both. So the surviving rule sent a reader staring at E100 to run `vale sync`, which fetches only what Packages declares and reports "Synced 0 package(s)" against a BasedOnStyles-only name. The remediation loop did not terminate. Reproduced end to end. The genuinely silent case is the reverse — declared in Packages and synced, but absent from BasedOnStyles — and it is now the one labelled as such. Testing also turned up that StylesPath must exist as a directory even when Vale is the only style (E201, exit 2), which was documented nowhere. references/configuration-reference.md gains a seven-row resolution matrix, each row backed by a fixture. Its Frontmatter Scopes section claimed provenance from the vale.sh research corpus, which contains no frontmatter material at all; it is house-verified and now says so under its own slug. Issue #99's wave-3 comment recorded this defect as found and repaired. It was not — the file was byte-identical to the commit that introduced it, so nothing here was treated as already correct. Refs #99
3.3 KiB
3.3 KiB
name, description, metadata
| name | description | metadata | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| vale-config | Use when installing or configuring Vale, the prose/style linter — writing a `.vale.ini` whose styles are fetched and actually activated — even when the user says only "set up prose linting". Not running Vale on an existing config -> `vale-run`. |
|
Gotchas
- A style in
BasedOnStylesthat is neither built-in nor a directory underStylesPathfails hard, not silently:E100 [loadStyles], exit 2, nothing linted. vale syncalone does not clear thatE100. Sync fetches only what the top-levelPackageskey declares, so against aBasedOnStyles-only name it reportsSynced 0 package(s)and exits 0, fetching nothing. Add the style toPackages, then sync. A style lints only once it is in both keys — and the reverse case is silent, exiting 0.- Only package styles need fetching: built-in
Vale, and any style whose YAML is already committed underStylesPath, lint with noPackagesentry and no sync. .vale.iniis order-sensitive: core settings first, then[formats], then glob sections. Anything written below a glob header applies only to files matching that glob.- A rule scoped to
text.frontmatter.<key>silently matches nothing when the field spans multiple lines in most YAML forms. If you scope a rule to frontmatter, readreferences/configuration-reference.mdfirst.
Setup workflow
- Install the
valebinary:brew install vale(macOS),snap install vale(Linux),choco install vale(Windows), ordocker pull jdkato/vale. - Pick a
StylesPath(conventionallystyles) and create it. This is where all styles, dictionaries, and vocab live. - Write
.vale.iniat the project root with at minimum:StylesPath = styles MinAlertLevel = suggestion [*.md] BasedOnStyles = ValeValehere is the built-in style (Vale.Spelling,Vale.Terms,Vale.Avoid,Vale.Repetition) — no download needed, it always works. - Add third-party styles (optional) by declaring them in
Packages, then activating them in the same or another glob'sBasedOnStyles:Packages = Google, write-good [*.md] BasedOnStyles = Vale, Google, write-good - Sync: run
vale syncto download everything listed inPackagesintoStylesPath. - Verify activation: confirm every style named in
Packagesalso appears in at least one glob'sBasedOnStyles— an unreferenced package downloads but never lints anything.
For the full .vale.ini field reference (formats mapping, vocab, local overrides, custom rule header fields) and the verified style-resolution matrix — which error each misconfiguration raises, and the two that exit 0 while linting nothing — read references/configuration-reference.md.
Custom styles
A custom style is just a new subdirectory under StylesPath, holding one YAML file per rule:
styles/
└── MyStyle/
└── NoJargon.yml
Each rule file needs extends (the check it implements, e.g. existence) and message at minimum. Activate the style the same way as any other: add MyStyle to BasedOnStyles for the relevant glob. If a rule needs a field beyond those two, read references/configuration-reference.md for the full rule header field table.