Language Server

harper-ls is the Language Server Protocol frontend for Harper. Out of the box, it has built-in support for parsing the comments of most programming languages, as well as any and all Markdown files.

Installation

Scoop

You can install Harper on Windows through Scoop .

scoop install harper

Homebrew

You can install Harper on macOS and Linux through Homebrew .

brew install harper

Arch Linux

Stable Release

The latest stable release is available through the extra repo :

sudo pacman -S harper

Bleeding-Edge

If you want the latest bleeding-edge, you can install harper-git from the Arch User Repository with your favorite AUR helper:

paru -S harper-git
# or yay -S harper-git, etc.

Nixpkgs/NixOS

You may install Harper via Nixpkgs . You can install the harper package via any of the normal methods such as adding it to environment.systemPackages. You can try Harper within an ephemeral shell using:

nix-shell -p harper

or if you have the nix-command and flakes experimental features enabled:

nix shell 'nixpkgs#harper'

Cargo

If you have Rust installed, harper-ls is on crates.io , so you can simply run:

cargo install harper-ls --locked

For this to work, make sure that ~/.cargo/bin is in your system $PATH. If you are on a Debian-based Linux distribution, you may need to install build-essential.

GitHub Releases

If none of the previous installation methods are available to you, we also provide portable pre-built binaries on GitHub .

Dictionaries

harper-ls has four kinds of dictionaries: user, workspace, file-local, and static dictionaries. All four dictionaries are combined and used together when spell checking files.

User Dictionary

Each user of harper-ls has their own dictionary, created on-demand the first time that a word is added to it, which by default, is located at the following paths on each operating system:

This dictionary is a simple line-separated word list in plaintext. You can add and remove words at will. Code actions on misspelled words allow you to add elements to this list. Additionally, its location is configurable .

Workspace Dictionary

Each workspace in which you use harper-ls has its own dictionary, which by default is located at .harper-dictionary.txt in the root of the workspace.

This dictionary is a simple line-separated word list in plaintext. You can add and remove words at will. Code actions on misspelled words allow you to add elements to this list. Additionally, its location is configurable .

File-Local Dictionary

Sometimes, you'll encounter a word (or name) that is only valid within the context of a specific file. In this case, you can add this file-specific word to a file-local dictionary using code actions. Any words added to this dictionary will only be included in the combined dictionary when spell checking a file at that specific path.

You can find the file-local dictionaries in the following directories by default on each operation system:

The format of these files is identical to user dictionaries and their location can also be configured .

Static Dictionary

The static dictionary is built into the binary and is (as of now) immutable. It contains almost all words you could possibly encounter.

We do take pull requests or issues for adding words to the static dictionary. Read the documentation on the matter before you do .

Code Actions

harper-ls has code actions that help in quickly dealing with spelling or grammar errors you encounter. The examples below assume that you have misspelled "contained" as "containes" and have selected it to apply a code action to it.

Ignore Comments

harper-ls supports skipping comment blocks that contain any of following:

• harper:ignore
• harper: ignore
• spellcheck:ignore
• spellcheck: ignore
• spell-checker:ignore
• spell-checker: ignore
• spellchecker:ignore
• spellchecker: ignore

You may notice that the last four ignore comments are the same with some of CSpell's ignore comments. That is intentional in case users wish to use Harper and CSpell together.

Here's an example of how these comments can be used:

// harper:ignore this line will not be spellcheckd
function sample() {
	// harper: ignore
	// This line and any other line after it
	// will also not be spellcheckd

	// including this this one
}

In the above example, "spellcheckd", "this this", and other spelling or grammar errors will not be flagged.

Configuration

harper-ls expects a JSON object with a harper-ls key that contains your configs:

{
	"harper-ls": {
		// Your config goes here...
	}
}

Directories

These paths are always resolved relative to the root of the workspace in which harper-ls was invoked.

Linters

These configs are under the linters key:

{
	"harper-ls": {
		"linters": {
			// Your linter configs go here...
		}
	}
}

The list of linters together with their descriptions can be found at our rules page . All linters are of boolean type. Here's an example config with some of them and their default values:

{
	"harper-ls": {
		"linters": {
			"SpellCheck": true,
			"SpelledNumbers": false,
			"AnA": true,
			"SentenceCapitalization": true,
			"UnclosedQuotes": true,
			"WrongQuotes": false,
			"LongSentences": true,
			"RepeatedWords": true,
			"Spaces": true,
			"Matcher": true,
			"CorrectNumberSuffix": true
		}
	}
}

Code Actions

These configs are under the codeActions key:

{
	"harper-ls": {
		"codeActions": {
			// Your code action configs go here...
		}
	}
}

Markdown

These configs are under the markdown key:

{
	"harper-ls": {
		"markdown": {
			// Your Markdown configs go here...
		}
	}
}

Other Configs

Supported Languages

harper-ls supports a wide variety of programming and markup languages.

Want your language added? Let us know by commenting on this issue .