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

source_keys

source_keys
context7-websites-vale-sh

Vale troubleshooting reference

Inline suppression syntax by format

Markdown uses HTML comments — the MDX {/* */} form does not suppress anything in a plain .md file:

<!-- vale off -->
This text will be ignored.
<!-- vale on -->

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:

Markdown:

<!-- vale Style.Redundancy["ACT test","OTHER"] = NO -->
This is some text ACT test
<!-- vale Style.Redundancy["ACT test","OTHER"] = YES -->

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:

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:

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.