Defame1297
f40deada86
vale-config deleted "settings in a glob section only apply to files matching that glob" — the single most common Vale misconfiguration. Nothing in either lint skill told an agent that BasedOnStyles under `[*.md]` governs `.md` only; the nearest survivor was a parenthetical in a reference file the skill opens only for the full field listing. Restored to the always-loaded body, at the point of use. vale-config also never mentioned `[formats]` or MDX at all, leaving the whole decision in that same reference file. Verified against Vale 3.15.2: an unmapped `.mdx` covered by one of your globs is `E100 [lintMDX]`, exit 2, and every other file in that invocation produces no output whatsoever. Because the failure is invocation-wide rather than per-file, it belongs in the Gotchas. The crash requires a glob that actually covers `.mdx` — under `[*.md]` the file is skipped and nothing fails — so the Gotcha states that condition rather than the broader claim that any `.mdx` in the tree kills the run. The mapping-versus-mdx2vast attribution disagreed across the two skills: vale-run said `[formats] mdx = md` is "what vale-config recommends" while vale-config presented it as a bare either/or. Fixed on the source side by having vale-config actually recommend it and say why, which makes vale-run's existing sentence true with no edit to vale-run. Refs: #117
114 lines
6.7 KiB
Markdown
114 lines
6.7 KiB
Markdown
---
|
|
topic: configuration-reference
|
|
source_keys:
|
|
- context7-websites-vale-sh
|
|
- house-vale-3-15-2-repro
|
|
---
|
|
|
|
## 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:
|
|
|
|
```ini
|
|
[formats]
|
|
mdx = md
|
|
```
|
|
|
|
`mdx` is the case that matters, because Vale 3.15.2 has no built-in MDX support. The mapping above is not cosmetic: it is what lets `.mdx` files lint with nothing else installed. Leave it out and Vale takes the native MDX path, which shells out to an external `mdx2vast` binary — absent from `PATH`, the run dies with `E100 [lintMDX] Runtime error / mdx2vast not found`, exit 2, and every other file in the same invocation goes unlinted too. Take the mapping: it is this skill's recommended default, because it needs nothing installed, and it is the branch `vale-run` assumes when it documents inline suppressions. Install `mdx2vast` (`npm install -g mdx2vast`) only when something else in the toolchain already needs the native MDX parser.
|
|
|
|
The choice also decides the inline-suppression syntax, and it is inverted between the two: mapped to `md`, `.mdx` takes Markdown's `<!-- vale off -->`; native, it takes `{/* vale off */}`. `vale-run`'s `references/troubleshooting.md` carries the verified matrix.
|
|
|
|
## Vocabularies
|
|
|
|
Reference a named vocabulary (a folder of accept/reject word lists under `StylesPath`) via `Vocab`, then apply styles per glob:
|
|
|
|
```ini
|
|
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:
|
|
|
|
```ini
|
|
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`.
|
|
|
|
## Style Resolution
|
|
|
|
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").
|
|
|
|
`Packages` (top-level, what `vale sync` downloads) and `BasedOnStyles` (per-glob, what activates) are separate keys: a style lints a file only once it is in both. Every row below reproduced against Vale 3.15.2 (slug `house-vale-3-15-2-repro`):
|
|
|
|
| Configuration | Result |
|
|
|---|---|
|
|
| `BasedOnStyles` names a style with no directory under `StylesPath`, not built-in | `E100 [loadStyles] Runtime error` — `style 'X' does not exist on StylesPath`, exit 2 |
|
|
| `StylesPath` directory itself absent, even with only `Vale` active | `E201 Invalid value` — `The path '...' does not exist`, exit 2 |
|
|
| `vale sync` with a name in `BasedOnStyles` but not `Packages` | `SUCCESS Synced 0 package(s)`, exit 0, nothing downloaded — the next lint repeats the `E100` |
|
|
| `vale sync` with the name added to `Packages` | package lands under `StylesPath`, exit 0; lint then loads it |
|
|
| Style in `Packages` and synced, but in no glob's `BasedOnStyles` | 0 findings, exit 0 — downloads, never lints, indistinguishable from a clean run |
|
|
| `BasedOnStyles` names an *empty* directory under `StylesPath` | 0 findings, exit 0 — loads and lints nothing; `vale sync` never produces this state |
|
|
| Built-in `Vale`, or a style's YAML committed under `StylesPath` | lints immediately, no `Packages` entry, no sync |
|
|
| Core option (`StylesPath`, `MinAlertLevel`, `Vocab`, `IgnoredScopes`, `SkippedScopes`) below a `[glob]` header | `E201 Invalid value` — `'X' is a core option; it should be defined above any syntax-specific options ([...])`, exit 2 |
|
|
| `Packages` below a `[glob]` header | no error, exit unaffected — parsed as a per-glob rule toggle (`SChecks: {"*.md": {"Packages": false}}` in `ls-config`), so `vale sync` reports `Synced 0 package(s)` and downloads nothing |
|
|
|
|
## Frontmatter Scopes
|
|
|
|
House-verified behaviour, not documented on vale.sh — reproduced locally against Vale 3.15.2 (slug `house-vale-3-15-2-repro`).
|
|
|
|
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. 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.
|