Creating a plugin

Learn how to integrate Vale with other tools and services.

Vale can provide JSON output that extensions can use.

Your extension should call the Vale CLI, 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 VS Code extension uses the buildCommand method to create a reusable command the extension can call with a variety of parameters.

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 a Name for the action and Params 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 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 VS Code extension uses the shared handleJSON method to take each check object and convert it to a VS Code 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?
  • Custom paths for the Vale CLI binary, configuration, or styles paths
← Configuration
JetBrains →