Creating a plugin
Vale can provide JSON output that extensions can use. How you get this output can depend on if you use Vale server or CLI.
With Vale 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.
vale --output JSON {path/file}
Look at how the VSCode extension uses the buildCommand
method to create a reusable command the extension can call with a variety of parameters.
With Vale Server
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 ".".
The VSCode extension does something similar, creating a postString
method that handles creating the request and response to the endpoint, that the extension calls when needed.
JSON output of checks
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.
{
"index.md": [
{
"Action": {
"Name": "",
"Params": null
},
"Check": "write-good.Passive",
"Description": "",
"Line": 6,
"Link": "",
"Message": "'was created' may be passive voice. Use active voice if you can.",
"Severity": "warning",
"Span": [
59,
69
],
"Match": "was created"
},
]
}
Each object contains the following information:
Action
: An action or change to the text that Vale server can take with a rule, containing aName
for the action andParams
passed to the action.Check
: The rule set 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 ruleMessage
: Help text output by the ruleSeverity
: 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.
General tips
Configuration options
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
Vale server API reference
You can find the full API reference for Vale server in the OAS spec.