Creating a plugin

Learn how to integrate Vale with other tools and services.

There are two ways to integrate Vale with other tools and services: using the Vale CLI directly or using the Vale Language Server (vale-ls).

For any application that supports the Language Server Protocol, we recommend using the Vale Language Server.

vale-ls

The Vale Language Server (vale-ls) is distributed as a standalone binary that acts as a wrapper around a local installation of Vale, providing autocomplete, diagnostics, and hover popups, and more. The server supports the following initializationParams:

ParameterDefaultDescription
installValetrueAutomatically install and update Vale to a vale_bin folder in the same location as vale-ls. If false, the vale executable needs to be available on the user’s $PATH.
filterNoneAn output filter to apply when calling Vale.
configPathNoneAn absolute path to a .vale.ini file to be used as the default configuration.
syncOnStartuptrueRuns vale sync upon starting the server.

To use the server, you’ll need to download the latest release from GitHub.

--output=JSON

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 file_path

The result is a JSON object that contains the path to the file and an array of objects that contain the line number, the error message, and the matched text.

{
  "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.

← Configuration
JetBrains →