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

> Find Automattic/harper documentation within its repository. Explore Markdown files in packages/web/src/routes/docs/ and key README/ARCHITECTURE files for a complete guide.

- Repository: [Automattic/harper](https://github.com/Automattic/harper)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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`](https://github.com/Automattic/harper/blob/main/README.md) and [`ARCHITECTURE.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/README.md)** — Provides the repository overview, quick start instructions, and top-level links to all specialized documentation.
- **[`ARCHITECTURE.md`](https://github.com/Automattic/harper/blob/main/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

```javascript
// 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

```bash

# Install via Cargo

cargo install --locked harper-cli

# Lint a Markdown file

harper-cli lint docs/example.md

```

### Configuring the VS Code Extension

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

```

### Writing a Custom Weir Rule

```weir
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`](https://github.com/Automattic/harper/blob/main/ARCHITECTURE.md)** — System diagrams and component responsibilities.
- **[`README.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/README.md)** and **[`ARCHITECTURE.md`](https://github.com/Automattic/harper/blob/main/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`](https://github.com/Automattic/harper/blob/main/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.