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
2.7 KiB
2.7 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 already underStylesPathfinds nothing untilvale syncfetches it — a clean run is not proof anything linted. .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), 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.