Where to Find Documentation for Automattic/harper: A Complete Guide

All documentation for the Automattic/harper grammar checker lives inside the repository itself as Markdown files, primarily located under packages/web/src/routes/docs/ and in key files like README.md and ARCHITECTURE.md at the repository root.

The Harper project maintains comprehensive, self-hosted documentation that covers everything from API usage to architecture decisions. Instead of relying on external wikis, the project stores all docs as version-controlled Markdown files rendered via Vite and SvelteKit, ensuring that documentation for Automattic/harper stays synchronized with the codebase.

High-Level Overview and Getting Started

The best starting point for understanding Harper’s purpose and privacy model is the About page located at packages/web/src/routes/docs/about/+page.md. This file explains the project's design philosophy, versioning policy, and supported dialects.

For immediate orientation, examine these two critical files in the repository root:

• README.md — Provides the repository overview, quick start instructions, and top-level links to all specialized documentation.
• ARCHITECTURE.md — Contains high-level system diagrams explaining the relationship between the Rust core (harper-core), the WASM build (harper-wasm), the language server, and browser extensions.

API and Integration Guides

The harper.js JavaScript library documentation resides under packages/web/src/routes/docs/harperjs/:

• introduction/+page.md — Installation instructions for browsers and Node.js, plus basic configuration of lint rules.
• linting/+page.md — Detailed API reference for exported functions including lint(), configure(), and addToDictionary().

For Language Server Protocol integration with editors, see packages/web/src/routes/docs/integrations/language-server/+page.md. Editor-specific configuration guides live in adjacent directories:

• packages/web/src/routes/docs/integrations/vscode-plugin/+page.md — VS Code settings and extension details.
• packages/web/src/routes/docs/integrations/chrome-extension/+page.md — Browser extension installation and UI features.

Contributor and Rule Authoring Documentation

Developers extending Harper’s grammar engine should consult packages/web/src/routes/docs/contributors/author-a-rule/+page.md. This guide covers the Weir domain-specific language for creating new grammar rules, writing test suites, and integrating rules into harper-core.

Practical Code Examples

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

# Install via Cargo

cargo install --locked harper-cli

# Lint a Markdown file

harper-cli lint docs/example.md

Configuring the VS Code Extension

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

Key Documentation Files Reference

The following paths map to specific documentation topics within the repository:

• packages/web/src/routes/docs/about/+page.md — Project overview, privacy model, and architecture.
• packages/web/src/routes/docs/harperjs/introduction/+page.md — JavaScript library installation and usage.
• packages/web/src/routes/docs/harperjs/linting/+page.md — API methods including lint() and configure().
• packages/web/src/routes/docs/integrations/language-server/+page.md — LSP setup for editors like Neovim, Helix, and Zed.
• packages/web/src/routes/docs/integrations/vscode-plugin/+page.md — VS Code specific configuration.
• packages/web/src/routes/docs/integrations/chrome-extension/+page.md — Browser extension documentation.
• packages/web/src/routes/docs/contributors/author-a-rule/+page.md — Weir language rule authoring.
• ARCHITECTURE.md — System diagrams and component responsibilities.
• README.md — Entry point with quick start links.

Summary

• All documentation for Automattic/harper is stored as Markdown files in packages/web/src/routes/docs/ and rendered via Vite and SvelteKit.
• The README.md and ARCHITECTURE.md files provide high-level orientation and system design context.
• harper.js API references are located in packages/web/src/routes/docs/harperjs/ with guides for the lint() and configure() functions.
• Editor integration docs for VS Code, Neovim, and LSP-compatible editors reside in packages/web/src/routes/docs/integrations/.
• Contributors can find Weir rule authoring instructions in the contributors documentation section.

Frequently Asked Questions

Where is the official documentation website generated from?

The official Harper website renders Markdown files located in packages/web/src/routes/docs/ using a Vite and SvelteKit build pipeline. You can read the raw documentation directly on GitHub in the master branch or clone the repository to browse it locally.

How do I find the API documentation for the JavaScript library?

The harper.js API documentation resides in packages/web/src/routes/docs/harperjs/linting/+page.md. This file documents exported functions such as lint(), configure(), and addToDictionary(), along with their parameters and configuration options.

What file contains the architecture overview for the Harper project?

The ARCHITECTURE.md file at the repository root contains high-level diagrams explaining the relationship between harper-core (Rust), harper-wasm (WebAssembly bindings), and the surrounding tooling including the language server and browser extensions.

How can I learn to write new grammar rules for Harper?

Rule authoring documentation lives in packages/web/src/routes/docs/contributors/author-a-rule/+page.md. This guide explains the Weir domain-specific language syntax for defining grammar patterns, creating test suites, and submitting new rules to the core engine.

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