---
name: vale-config

description: >
  Use when installing or configuring Vale, the cross-platform prose/style linter — setting up
  .vale.ini, choosing a StylesPath, adding built-in, third-party, or custom styles, and activating
  them per file glob via BasedOnStyles. Covers the setup side of Vale only: getting a project from
  "no Vale config" to "vale sync runs clean and BasedOnStyles is wired up correctly". Use even if the
  user doesn't say "Vale" explicitly — "set up prose linting", "lint our docs for style", "enforce a
  vocabulary/terminology list in markdown" all apply. Do not use when the user wants to actually run
  Vale and interpret its output on existing config — use vale-run for that.

metadata:
  category: lint
  version: "0.1.0"
  source_keys:
    - context7-websites-vale-sh
---

## Gotchas

- Installing the `vale` binary installs no styles, but only *package* styles need fetching. A fresh `.vale.ini` naming a style in `BasedOnStyles` that is declared in `Packages` will fail or find nothing until `vale sync` downloads it. A built-in style (`Vale`) or a style whose YAML rule files are already committed under `StylesPath` lints immediately, with no `Packages` entry and no sync.
- `.vale.ini` is order-sensitive: global (core) settings first, then the optional `[formats]` section, then glob sections (`[*]`, `[*.md]`, …). Settings in a glob section only apply to files matching that glob.
- `Packages` (top-level, fetched by `vale sync`) and `BasedOnStyles` (per-glob, activates) are separate keys — a style only lints files once it's in both. This is the step people forget.
- 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 with a deliberately-bad fixture: a `>` folded block scalar, plain (unquoted) continuation lines, and single- or double-quoted multi-line scalars each yield 0 findings and exit 0, silently and with no error; a `|` literal block scalar spanning the same 2+ lines lints normally and exits 1. Do not assume `|` and `>` 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.

## 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), 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. See `references/configuration-reference.md` for the full rule header field table.