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
61 lines
3.3 KiB
Markdown
61 lines
3.3 KiB
Markdown
---
|
|
name: vale-config
|
|
|
|
description: >
|
|
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`.
|
|
|
|
metadata:
|
|
category: lint
|
|
version: "0.1.1"
|
|
source_keys:
|
|
- context7-websites-vale-sh
|
|
- house-vale-3-15-2-repro
|
|
---
|
|
|
|
## Gotchas
|
|
|
|
- A style in `BasedOnStyles` that is neither built-in nor a directory under `StylesPath` fails hard, not silently: `E100 [loadStyles]`, exit 2, nothing linted.
|
|
- `vale sync` alone does not clear that `E100`. Sync fetches only what the top-level `Packages` key declares, so against a `BasedOnStyles`-only name it reports `Synced 0 package(s)` and exits 0, fetching nothing. Add the style to `Packages`, 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 under `StylesPath`, lint with no `Packages` entry and no sync.
|
|
- `.vale.ini` is 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, read `references/configuration-reference.md` first.
|
|
|
|
## Setup workflow
|
|
|
|
- [ ] **Install** the `vale` binary: `brew install vale` (macOS), `snap install vale` (Linux), `choco install vale` (Windows), or `docker pull jdkato/vale`.
|
|
- [ ] **Pick a `StylesPath`** (conventionally `styles`) and create it. This is where all styles, dictionaries, and vocab live.
|
|
- [ ] **Write `.vale.ini`** at the project root with at minimum:
|
|
```ini
|
|
StylesPath = styles
|
|
MinAlertLevel = suggestion
|
|
|
|
[*.md]
|
|
BasedOnStyles = Vale
|
|
```
|
|
`Vale` here 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's `BasedOnStyles`:
|
|
```ini
|
|
Packages = Google, write-good
|
|
|
|
[*.md]
|
|
BasedOnStyles = Vale, Google, write-good
|
|
```
|
|
- [ ] **Sync**: run `vale sync` to download everything listed in `Packages` into `StylesPath`.
|
|
- [ ] **Verify activation**: confirm every style named in `Packages` also appears in at least one glob's `BasedOnStyles` — 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.
|