holocron/plugins/lint/skills/vale-run/references/troubleshooting.md

source_keys

source_keys
context7-websites-vale-sh

Vale troubleshooting reference

Inline suppression syntax by format

Markdown/MDX:

{/* vale off */}
This text will be ignored.
{/* vale on */}

Org mode:

# 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:

{/* 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:

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

If a CI job fails solely because Vale returns a non-zero exit code on found 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.

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:

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:

      - 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

$ 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.