Defame1297
45cd26045a
Description 657 -> 244 chars, body 504 -> 342 words, Gotchas 50% -> 24%. The 50% was the worst ratio in the corpus and a real inverted body, not the denominator artefact the ratio usually flags: half the body was a Gotchas section doing duty as reference material. A clean-context audit caught the split leaving a false statement behind. Gotcha 1's kernel lost the qualifier that only package styles need fetching, so it asserted that any style vale sync has not fetched fails -- contradicting the same file twice, since the built-in Vale style and any committed custom style are never fetched. An agent adding a custom style would have added a spurious Packages entry and broken vale sync outright. The qualifier is restored in the body rather than behind a fourth reference pointer. Also corrects the moved fixture's framing, which tabulated a control row under a heading claiming it came from a multi-line fixture. Refs #99
3.8 KiB
topic, source_keys
| topic | source_keys | |
|---|---|---|
| configuration-reference |
|
Core Settings
| Key | Type | Purpose |
|---|---|---|
StylesPath |
string | Path to all Vale-related resources (styles, dictionaries, vocab). |
Packages |
string[] | Packages to download and install via vale sync. |
Vocab |
string[] | Vocabularies to load. |
MinAlertLevel |
enum | Minimum severity to report: suggestion, warning, or error. |
IgnoredScopes |
enum | Inline-level HTML tags to ignore. |
SkippedScopes |
enum | Block-level HTML tags to ignore entirely. |
Format Associations
Map an unrecognized extension onto a supported one so Vale lints it with the right parser — an extension-level substitution only, it does not add new file-type support:
[formats]
mdx = md
Vocabularies
Reference a named vocabulary (a folder of accept/reject word lists under StylesPath) via Vocab, then apply styles per glob:
StylesPath = styles
Vocab = Blog
[*]
BasedOnStyles = Vale, MyStyle
Local Overrides
A project can layer a local .vale.ini that overrides StylesPath, adds packages, and changes BasedOnStyles for a subset of files — local settings merge with or override the global ones:
StylesPath = localpath
Packages = write-good
[*.md]
BasedOnStyles = write-good
Rule Header Fields
Individual rule YAML files (under a style's directory) support these header fields:
| Field | Required | Default | Purpose |
|---|---|---|---|
extends |
yes | — | Check this rule extends (e.g. existence). |
message |
yes | — | Message shown when triggered; supports %s formatting per check type. |
level |
no | suggestion |
Severity: suggestion, warning, or error. |
scope |
no | text |
Scope the rule applies to (e.g. heading). |
link |
no | — | URL with more info about the rule. |
limit |
no | — | Max number of triggers per file. |
vocab |
no | true |
Set false to disable active vocabularies for this rule. |
Checks
The underlying functions a rule's extends field can reference: existence, substitution, occurrence, repetition, consistency, conditional, capitalization, metric, spelling, sequence, script.
Built-in Style
Only package styles need fetching. A style whose YAML rule files are already committed under StylesPath lints immediately, with no Packages entry and no vale sync; the same is true of the built-in Vale style, which ships with the binary and contains four rules:
Vale.Spelling— spell-checks against Hunspell-compatible dictionaries in<StylesPath>/config/dictionaries.Vale.Terms— enforces the project's accepted vocabulary terms.Vale.Avoid— enforces the project's rejected vocabulary terms.Vale.Repetition— flags repeated words (e.g. "the the").
Frontmatter Scopes
A rule scoped to text.frontmatter.<key> (e.g. text.frontmatter.description) matches reliably when that field's value is a single physical line, and breaks on most — not all — multi-line forms.
Confirmed against Vale 3.15.2, multi-line forms spanning 2+ lines:
| Frontmatter value form | Result |
|---|---|
| Single physical line (control) | Lints, exits 1 |
| literal block scalar |
Lints, exits 1 |
> folded block scalar |
0 findings, exits 0 |
| Plain (unquoted) continuation lines | 0 findings, exits 0 |
| Single- or double-quoted multi-line scalar | 0 findings, exits 0 |
The silent cases produce no error of any kind, so a passing run is indistinguishable from a clean one. Do not assume a literal block scalar and a folded one behave alike — reproduce both against your own config before trusting a frontmatter-scoped rule in production. If the field is commonly authored in one of the broken forms, flatten it to one physical line ahead of the vale call rather than relying on the scope alone.