holocron/plugins/lint/docs/research/docs/vale/troubleshooting.md

topic, source_keys

topic	source_keys
troubleshooting	context7-websites-vale-sh

Suppressing False Positives Inline

Vale supports inline markup comments to disable checks for a section of content. Syntax varies 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

Rather than disabling all checks, target one rule and specific known-exception strings, then re-enable:

{/* vale Style.Redundancy["ACT test","OTHER"] = NO */}
This is some text ACT test
{/* vale Style.Redundancy["ACT test","OTHER"] = YES */}

This is the preferred fix for recurring false positives on specific terms — it keeps the rule active everywhere else instead of disabling it project-wide.

Ignoring Words in Spell Check

The spelling check accepts an ignore list of external plain-text files, so known 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/incorrect results (e.g. 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.