Where to Find Documentation for Automattic/harper: Complete Guide to User Guides and API References

All documentation for Automattic/harper is self-hosted within the repository itself, rendered on the Harper website via a Vite + SvelteKit build, and available as raw Markdown files directly on GitHub under packages/web/src/routes/docs/.

The Harper project is an open-source grammar checker built in Rust with WebAssembly targets and language-server support. Whether you are integrating the JavaScript library, configuring the LSP client, or authoring custom grammar rules, the documentation is maintained as Markdown source files inside the repository, allowing you to read them online, clone them locally, or view them rendered on the official website.

User-Facing Documentation Structure

The primary documentation lives in packages/web/src/routes/docs/ and covers everything from high-level concepts to specific editor integrations.

High-Level Overview and Getting Started

For an introduction to Harper’s architecture, privacy model, and versioning policy, see packages/web/src/routes/docs/about/+page.md. If you are integrating the JavaScript library, the getting-started guide at packages/web/src/routes/docs/harperjs/introduction/+page.md walks through installation, browser vs. Node usage, and lint rule configuration.

API Reference for harper.js

The detailed API reference for exported functions like lint, configure, and addToDictionary is located at packages/web/src/routes/docs/harperjs/linting/+page.md. This file documents method signatures, optional configuration objects (such as dialect: 'american'), and return value structures.

Editor and Integration Guides

Documentation for specific integrations is organized by platform:

• Language Server Protocol (LSP): Configuration for VS Code, Neovim, Helix, and Zed is covered in packages/web/src/routes/docs/integrations/language-server/+page.md
• VS Code Extension: Specific UI features and settings for the VS Code plugin are documented at packages/web/src/routes/docs/integrations/vscode-plugin/+page.md
• Browser Extensions: Chrome and Firefox installation instructions live in packages/web/src/routes/docs/integrations/chrome-extension/+page.md
• Other Editors: Separate Markdown files exist for Neovim, Emacs, Sublime Text, and Obsidian in the same integrations/ directory.

Developer and Contributor Documentation

Rule Authoring with Weir

To create new grammar rules, navigate to packages/web/src/routes/docs/contributors/author-a-rule/+page.md. This guide covers the Weir domain-specific language for pattern matching, writing test suites, and integrating rules into harper-core.

Architecture Overview

For a high-level diagram of component responsibilities—including the Rust core (harper-core), WASM bindings (harper-wasm), and the desktop application—consult [ARCHITECTURE.md](https://github.com/Automattic/harper/blob/master/ARCHITECTURE.md) in the repository root.

Package-Specific READMEs

Supplementary documentation exists at the package level:

• harper-core/README.md – Details on the core grammar engine, benchmarking, and testing
• harper-ls/README.md – Setup and configuration for the language-server implementation
• packages/harper.js/README.md – Usage guide for the JavaScript/WASM library
• packages/web/README.md – Build instructions for the documentation website itself

Accessing Documentation Online vs. Locally

All documentation files are stored on the master branch, meaning you can:

1. Browse on GitHub: Click any .md file in packages/web/src/routes/docs/ to read the raw source
2. Clone locally: Run git clone https://github.com/Automattic/harper.git and open the files in your preferred Markdown viewer
3. Visit the website: The Vite + SvelteKit build renders the same Markdown files as interactive HTML pages

Quick Start Code Examples

The documentation includes runnable snippets for common entry points.

Using harper.js in Node.js

// Install first: npm install @harperdev/harper

import { lint } from '@harperdev/harper';

const results = await lint(
  "This sentence has a typo, like teh.",
  { dialect: 'american' }
);

console.log(results);
// → [{ message: "Did you mean “the”? …", range: [31, 34], ... }]

Running the CLI via Cargo

# Install the CLI

cargo install --locked harper-cli

# Lint a Markdown file

harper-cli lint docs/example.md

Configuring VS Code Settings

// .vscode/settings.json
{
  "harper.enable": true,
  "harper.lintOnSave": true,
  "harper.dialect": "american"
}

Writing a Custom Weir Rule

expr main {
  word "foo" then word "bar"
}
let message = "Avoid “foo bar” phrasing."
let kind = "style"

Summary

• Primary documentation for Automattic/harper lives in packages/web/src/routes/docs/ as Markdown files rendered by Vite + SvelteKit
• Integration guides cover LSP setup, VS Code, browser extensions, and terminal editors like Neovim and Helix
• API references for harper.js detail the lint function and configuration options at packages/web/src/routes/docs/harperjs/linting/+page.md
• Contributor docs explain Weir rule authoring and core architecture in packages/web/src/routes/docs/contributors/ and ARCHITECTURE.md
• Package READMEs in harper-core/, harper-ls/, and packages/harper.js/ provide implementation-specific guidance

Frequently Asked Questions

Where is the official Harper documentation hosted?

The official documentation is self-hosted within the Automattic/harper repository itself under packages/web/src/routes/docs/. While the Harper website renders these files using Vite and SvelteKit, you can read the raw Markdown directly on GitHub or clone the repository to access them offline.

How do I integrate Harper with my code editor?

Editor integration is documented in the integrations/ subdirectory. For VS Code, see packages/web/src/routes/docs/integrations/vscode-plugin/+page.md. For Neovim, Helix, and other LSP-compatible editors, refer to packages/web/src/routes/docs/integrations/language-server/+page.md, which details the harper-ls binary configuration.

Can I create custom grammar rules for Harper?

Yes. The documentation at packages/web/src/routes/docs/contributors/author-a-rule/+page.md explains how to write rules using the Weir language, a domain-specific language for pattern matching text. You will learn to define expressions, set lint message severity, and add test suites to verify rule behavior.

Is there a quick reference for the harper.js API?

The API reference is located at packages/web/src/routes/docs/harperjs/linting/+page.md. It documents the primary lint function, optional configuration objects for dialect selection (American vs. British English), and methods for dictionary management such as addToDictionary.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}