Vale can provide JSON output that extensions can use. How you get this output can depend on if you use Vale server or CLI.
Your extension should call the Vale CLI binary, which the user of your plugin needs to have installed, setting the output to
JSON mode, along with any other arguments.
Your extension should call the Vale server
/vale endpoint, which the user of your plugin needs to have installed.
http://localhost:7777/vale with the text to lint in the
text parameter and
format as the file extension of the file to check, including the leading ".".
Whether using Vale CLI or Server, the JSON output of the checks configured to run is similar, consisting of a file name with an array of check objects.
Each object contains the following information:
Action: An action or change to the text that Vale server can take with a rule, containing a
Namefor the action and
Paramspassed to the action.
Check: The ruleset and rule triggered.
Description: A more detailed explanation for a rule. You can use it with custom output format or an editor integration's UI.
Line: The line that contains the error.
Link: Link to explanation of style guide rule
Message: Help text output by the rule
Severity: The error level.
Span: The start and finish characters on the line.
Match: The text matched.
A plugin should loop through these checks, and parse the values, to output them to an appropriate part of the IDE or editor interface.
For example, the VSCode extension uses the shared
handleJSON method to take each check object and convert it to a VSCode diagnostic that appears in the bottom status bar of the editor window. If a user uses Vale server, you can also implement some form of "fix" solution propagated from the rule to the JSON, to the IDE or editor with the
Action property. For example, in the Microsoft style ellipses check, the action is to offer to remove the ellipses.
If the editor or IDE allows for user-configured settings for a plugin, then some of the following are good settings to include:
- When to check a document with Vale, on every change, or on save?
- How to toggle between Vale CLI or Vale Server
- Custom paths for the Vale CLI binary, configuration, or styles paths
You can find the full API reference for Vale server in the OAS spec.