Defame1297
ff187ef9fc
Description 654 -> 294 chars, Gotchas 36% -> 19%. Body 698 -> 642 words: up from the first pass, because a clean-context audit found four defects whose fixes are net-additive text. The suppression-markup warning covered only one of the two paths that write it -- the list is case-based, so a recurring false positive goes straight to step 3 and never read step 2's warning. Hoisted above both. The CI-failure trigger, which the description advertises, had no path to the file holding its answer: the negative diagnosis 'if the alerts are warnings, Vale is not what failed the build' survived only in troubleshooting.md, which no CI-entered invocation loads. An agent would confidently prescribe --no-exit for a failure Vale never caused. The description had lost every prose-domain word -- no 'prose', no 'linter' -- while vale-config kept all of them, so 'check prose style' routed to the wrong skill of the pair. Accepts two soft SUGGESTIONs rather than dropping restored content; neither fails the gate. Refs #99
111 lines
3.5 KiB
Markdown
111 lines
3.5 KiB
Markdown
---
|
|
source_keys:
|
|
- context7-websites-vale-sh
|
|
---
|
|
|
|
# Vale troubleshooting reference
|
|
|
|
## Why a rule isn't applying
|
|
|
|
`vale ls-config` prints the fully-resolved, currently active configuration as JSON. Check that
|
|
before rereading `.vale.ini` — what is written in the config file is not necessarily what is
|
|
active, and the resolved output is the fastest way to see which styles and rules a run actually
|
|
loaded.
|
|
|
|
## Inline suppression syntax by format
|
|
|
|
Markdown uses HTML comments — the MDX `{/* */}` form does not suppress anything in a plain `.md` file:
|
|
```markdown
|
|
<!-- vale off -->
|
|
This text will be ignored.
|
|
<!-- vale on -->
|
|
```
|
|
|
|
MDX:
|
|
```mdx
|
|
{/* vale off */}
|
|
This text will be ignored.
|
|
{/* vale on */}
|
|
```
|
|
|
|
Org mode:
|
|
```org
|
|
# vale off
|
|
This text will be ignored.
|
|
# vale on
|
|
```
|
|
|
|
## Disabling a specific rule for specific matches
|
|
|
|
Targets one rule and specific known-exception strings, then re-enables — the preferred fix for a recurring false positive on a specific term, since it keeps the rule active everywhere else:
|
|
|
|
Markdown:
|
|
```markdown
|
|
<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->
|
|
This is some text ACT test
|
|
<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->
|
|
```
|
|
|
|
MDX:
|
|
```mdx
|
|
{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
|
|
This is some text ACT test
|
|
{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}
|
|
```
|
|
|
|
## Ignoring words in spell check
|
|
|
|
The `spelling` check accepts an `ignore` list of external plain-text files, so project-specific terms don't need touching the dictionary:
|
|
|
|
```yaml
|
|
extends: spelling
|
|
message: "Did you really mean '%s'?"
|
|
level: error
|
|
ignore:
|
|
- ignore1.txt
|
|
- ignore2.txt
|
|
```
|
|
|
|
## Plain-text fallback
|
|
|
|
If a file's syntax-aware parsing produces noisy or incorrect results (an unsupported or malformed format), rerun with `--ignore-syntax` to treat it as plain text instead of relying on the format-specific parser.
|
|
|
|
## CI failing unexpectedly
|
|
|
|
Only `error`-level alerts make Vale exit non-zero; `warning` and `suggestion` alerts are printed but exit `0`. If a CI job fails solely because of `error`-level alerts — not because the content is actually wrong for that pipeline stage — add `--no-exit` rather than suppressing the rule itself. This preserves the lint output while not gating the build on it. If the alerts are warnings or suggestions, Vale did not fail the job — look elsewhere.
|
|
|
|
## pre-commit integration
|
|
|
|
Vale ships a pre-commit hook definition. A typical setup runs `vale sync` once (with `pass_filenames: false`) plus the actual lint pass with CI-appropriate flags:
|
|
|
|
```yaml
|
|
repos:
|
|
- repo: https://github.com/errata-ai/vale
|
|
rev: 16d3a7f
|
|
hooks:
|
|
- id: vale
|
|
name: vale sync
|
|
pass_filenames: false
|
|
args: [sync]
|
|
- id: vale
|
|
args: [--output=line, --minAlertLevel=error]
|
|
```
|
|
|
|
If the project has documented a wrapper script for a known Vale scope/escaping limitation (see the Gotchas section of `SKILL.md`), point the second hook's `entry:` at that wrapper instead of at bare `vale`, even though the hook's `repo`/`rev`/`id` still come from the upstream definition above — only the invocation target changes:
|
|
|
|
```yaml
|
|
- id: vale
|
|
entry: <path-to-project-wrapper>
|
|
args: [--output=line, --minAlertLevel=error]
|
|
```
|
|
|
|
Using the upstream hook's bare `vale` entry in a project that has such a wrapper reintroduces exactly the bug the wrapper exists to fix.
|
|
|
|
## CI output for machine parsing
|
|
|
|
```bash
|
|
$ vale --output=JSON README.md
|
|
```
|
|
|
|
Use `--output=JSON` when a CI step needs to parse results programmatically rather than read the default CLI-formatted output.
|