Merge pull request #755 from mcecode/integration-docs

docs: update integrations section
Automattic · Mar 6, 2025 · c9a2efd · c9a2efd
2 parents 0da3835 + 8abfb4e
commit c9a2efd
Show file tree

Hide file tree

Showing 15 changed files with 422 additions and 315 deletions.
diff --git a/README.md b/README.md
@@ -43,8 +43,14 @@ Just make sure to read [our contribution guidelines first.](https://github.com/a
 ## Links
 
 - [Frequently Asked Questions](https://writewithharper.com/docs/faq)
+- [Obsidian Documentation](https://writewithharper.com/docs/integrations/obsidian)
 - [`harper-ls` Documentation](https://writewithharper.com/docs/integrations/language-server)
-- [Neovim Support](https://writewithharper.com/docs/integrations/neovim)
+- Supported Editors' Documentation
+  - [Visual Studio Code](https://writewithharper.com/docs/integrations/visual-studio-code)
+  - [Neovim](https://writewithharper.com/docs/integrations/neovim)
+  - [Helix](https://writewithharper.com/docs/integrations/helix)
+  - [Emacs](https://writewithharper.com/docs/integrations/emacs)
+  - [Zed](https://writewithharper.com/docs/integrations/zed)
 - [`harper.js` Documentation](https://writewithharper.com/docs/harperjs/introduction)
 - [Official Discord Server](https://discord.com/invite/JBqcAaKrzQ)
 

diff --git a/packages/vscode-plugin/README.md b/packages/vscode-plugin/README.md
@@ -1,35 +1,9 @@
 # Harper for VS Code
 
-Harper is the next-generation grammar checker for your code. It catches common stylistic errors, as well as complex grammatical or layout-related problems. It works for almost [all common programming languages](./language-server#Supported-Languages) and a number of markup formats.
+Harper is the next-generation grammar checker for your code. It catches common stylistic errors, as well as complex grammatical or layout-related problems. It works for almost [all common programming languages](https://writewithharper.com/docs/integrations/language-server#Supported-Languages) and a number of markup formats.
 
 If you use Rust, Java, JavaScript, or any number of other programming languages, your comments may end up as part of your API's documentation. If that's the case, grammatical mistakes in your code could be down-ranking your site on search results and tarnishing your reputation for quality.
 
 Most importantly, Harper runs on-device and uses barely any memory at all. That means you can get feedback on your work in milliseconds, dramatically increasing your iteration speed.
 
-## Installation
-
-Installation should be relatively straightforward.
-It just depends on which editor and marketplace you're using.
-
-If you use the official Microsoft Visual Studio Code release, go ahead and go to the marketplace and search for "Harper" and click "Install".
-You can also visit our [official page](https://marketplace.visualstudio.com/items?itemName=elijah-potter.harper&ssr=false#overview).
-
-If you use OpenVSX, for instance if you use VSCodium, you'll want to install from [here](https://open-vsx.org/extension/elijah-potter/harper).
-
-### Commands
-
-| Command                         | Id                              | Description         |
-| ------------------------------- | ------------------------------- | ------------------- |
-| Harper: Restart Language Server | `harper.languageserver.restart` | Restart `harper-ls` |
-
-### Settings
-
-| Setting                        | Type                                              | Default Value   | Description                                                                                                                                                 |
-| ------------------------------ | ------------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `harper-ls.path`               | `string`                                          | `""`            | Optional path to a `harper-ls` executable to use. Primarily useful if the bundled binary doesn't work in your system like in immutable Linux distributions. |
-| `harper-ls.linters.*`          | `boolean`                                         | Varies          | Detect and provide suggestions in a variety of common situations.                                                                                           |
-| `harper-ls.diagnosticSeverity` | `"error"`, `"hint"`, `"information"`, `"warning"` | `"information"` | How severe do you want diagnostics to appear in the editor?                                                                                                 |
-
-## Developing and Contributing
-
-See the [Development Guide](/packages/vscode-plugin/development-guide.md).
+You can learn more about [this extension](https://writewithharper.com/docs/integrations/visual-studio-code) and [Harper](https://writewithharper.com/docs/about) over at our [official website](https://writewithharper.com).
diff --git a/packages/vscode-plugin/development-guide.md b/packages/vscode-plugin/development-guide.md
@@ -1,48 +1,3 @@
 # Development Guide
 
-This document details how to develop the extension locally. If you're interested in how it's packaged for distribution, you can checkout the [Package VS Code Plugin](/.github/workflows/package_vscode_plugin.yml) workflow.
-
-## Notes
-
-- The extension code and its tests live in the `src` directory. Most changes you'll need to make will be there.
-- VS Code can only pickup the tasks and launch configurations set in `packages/vscode-plugin/.vscode` if this directory, `packages/vscode-plugin`, not the root of the Harper repository, is open.
-- You can look at the project's [`justfile`](/justfile) to see exactly what running the `just` recipes below do.
-
-## Prerequisites
-
-- Make sure to read the [Contributing guide](/CONTRIBUTING.md) and follow the "Setup Your Environment" section.
-- Before running or testing the extension using VS Code's Debugger, make sure you have `harper-ls` in `packages/vscode-plugin/bin`. You can either manually create the directory, compile `harper-ls`, and put it there or you can run `just test-vscode` or `just package-vscode` which will do that for you.
-
-## Running the Extension
-
-1. Open the Run and Debug view by selecting it from the Activity Bar or by pressing `Ctrl+Shift+D`.
-2. Choose `Run Extension`, if not chosen already.
-3. Click the play (Start Debugging) button or press `F5`.
-
-## Running the Tests
-
-### Using VS Code's Debugger
-
-1. Open the Run and Debug view by selecting it from the Activity Bar or by pressing `Ctrl+Shift+D`.
-2. Choose `Test Extension`, if not chosen already.
-3. Click the play (Start Debugging) button or press `F5`.
-
-### Using the Command Line
-
-```console
-just test-vscode
-```
-
-## Packaging and Installing the Extension
-
-1. Package the extension:
-
-   ```console
-   just package-vscode
-   ```
-
-2. Install the extension:
-
-   ```console
-   code --install-extension path/to/created/.vsix
-   ```
+This document has been moved to the [official documentation](https://writewithharper.com/docs/contributors/visual-studio-code).
diff --git a/packages/vscode-plugin/package.json b/packages/vscode-plugin/package.json
@@ -81,7 +81,7 @@
 					"scope": "resource",
 					"type": "boolean",
 					"default": false,
-					"description": "Make code actions appear in \"stable\" positions by placing code actions that should always be available like adding misspelled words in the dictionary first."
+					"description": "Make code actions appear in \"stable\" positions by placing code actions that should always be available, like adding misspelled words in the dictionary, first."
 				},
 				"harper.diagnosticSeverity": {
 					"scope": "resource",

diff --git a/packages/web/src/app.css b/packages/web/src/app.css
@@ -7,6 +7,10 @@
 		@apply list-disc pl-4;
 	}
 
+	ol {
+		@apply list-decimal pl-4;
+	}
+
 	h1 {
 		@apply text-5xl py-4;
 	}
@@ -19,6 +23,10 @@
 		@apply text-xl sm:text-xl lg:text-2xl py-4;
 	}
 
+	h4 {
+		@apply font-bold;
+	}
+
 	p {
 		@apply lg:text-base md:text-lg xl:text-lg py-4;
 	}

diff --git a/packages/web/src/routes/docs/contributors/review/+page.md b/packages/web/src/routes/docs/contributors/review/+page.md
@@ -24,13 +24,13 @@ Most of our build tooling exists for Harper's various integrations.
 If you are testing `harper-core`, you can skip all the fluff and compile the patch using [Cargo](https://doc.rust-lang.org/cargo/) directly.
 
 ```bash
-cargo install --git https://github.com/automattic/harper --branch <branch-name> <binary-artifact>
+cargo install --git https://github.com/automattic/harper --branch <branch-name> <binary-artifact> --locked
 ```
 
 For example, for [PR #445](https://github.com/Automattic/harper/pull/455), we can install the patched version of the `harper-cli` debug tool with the following command:
 
 ```bash
-cargo install --git https://github.com/automattic/harper --branch somewhat-something harper-cli
+cargo install --git https://github.com/automattic/harper --branch somewhat-something harper-cli --locked
 ```
 
 From there, you can run the tool on any file with `harper-cli lint <path>`.

diff --git a/packages/web/src/routes/docs/contributors/visual-studio-code/+page.md b/packages/web/src/routes/docs/contributors/visual-studio-code/+page.md
@@ -0,0 +1,50 @@
+---
+title: Visual Studio Code
+---
+
+This document details how to develop the Visual Studio Code extension locally. If you're interested in how it's packaged and distributed, you can checkout the [Release VS Code Plugin](https://github.com/Automattic/harper/blob/master/.github/workflows/release_vscode_plugin.yml) workflow.
+
+## Notes
+
+- The extension code and its tests live in the `packages/vscode-plugin/src` directory. Most changes you'll need to make will be there.
+- VS Code can only pickup the tasks and launch configurations set in `packages/vscode-plugin/.vscode` if this directory, `packages/vscode-plugin`, not the root of the Harper repository, is open.
+- You can look at the project's [`justfile`](https://github.com/Automattic/harper/blob/master/justfile) to see exactly what running the `just` recipes below do.
+
+## Prerequisites
+
+- Make sure to [set up your environment](./environment).
+- Before running or testing the extension using VS Code's Debugger, make sure you have `harper-ls` in `packages/vscode-plugin/bin`. You can either manually create the directory, compile `harper-ls`, and put it there or you can run `just test-vscode` or `just package-vscode` which will do that for you.
+
+## Running the Extension
+
+1. Open the Run and Debug view by selecting it from the Activity Bar or by pressing `Ctrl+Shift+D`.
+2. Choose `Run Extension`, if not chosen already.
+3. Click the play (Start Debugging) button or press `F5`.
+
+## Running the Tests
+
+### Using VS Code's Debugger
+
+1. Open the Run and Debug view by selecting it from the Activity Bar or by pressing `Ctrl+Shift+D`.
+2. Choose `Test Extension`, if not chosen already.
+3. Click the play (Start Debugging) button or press `F5`.
+
+### Using the Command Line
+
+```bash
+just test-vscode
+```
+
+## Packaging and Installing the Extension
+
+1. Package the extension:
+
+   ```bash
+   just package-vscode
+   ```
+
+2. Install the extension:
+
+   ```bash
+   code --install-extension path/to/created/.vsix
+   ```
diff --git a/packages/web/src/routes/docs/faq/+page.md b/packages/web/src/routes/docs/faq/+page.md
@@ -7,7 +7,7 @@ title: Frequently Asked Questions
 **Short answer**: not yet.
 
 **Long answer:** at the time of writing, we've just released our first version of `harper.js` ([documentation here](./harperjs/introduction)), which will make it significantly easier to build such a product.
-That said, our road map has higher priority items at the moment, so don't expect the offical Harper maintainers to make an attempt in the near future.
+That said, our road map has higher priority items at the moment, so don't expect the official Harper maintainers to make an attempt in the near future.
 
 If you're interested in trying to make one, let us know how it goes.
 We might be able to help.
@@ -21,6 +21,6 @@ We are entirely open to PRs that add support.
 If you just want to be able to run grammar checking on your code's comments, it's actually quite straightforward.
 You can use [this PR as a model for what to do](https://github.com/Automattic/harper/pull/332).
 
-### Where Did the Name Harper Come From?
+## Where Did the Name Harper Come From?
 
 See [this blog post](https://elijahpotter.dev/articles/naming_harper).
diff --git a/packages/web/src/routes/docs/integrations/emacs/+page.md b/packages/web/src/routes/docs/integrations/emacs/+page.md
@@ -2,5 +2,59 @@
 title: Emacs
 ---
 
-Our Emacs support is limited and primarily provided by the community.
-You can see the longer discussion [here](https://github.com/Automattic/harper/discussions/150).
+Our Emacs integration is powered by [`harper-ls`](./language-server).
+
+## Required Setup
+
+Make sure you have [`harper-ls` installed](./language-server#Installation) on your system and available in your `PATH`.
+
+Since version 29, Emacs has had native support for the Language Server Protocol through [Eglot](https://www.gnu.org/software/emacs/manual/html_mono/eglot.html), so all you have to do is configure it to use `harper-ls` in your `init.el`:
+
+```elisp title=init.el
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               '(text-mode . ("harper-ls" "--stdio"))))
+```
+
+where `text-mode` can be set to any, some, or all major modes that correspond to the [languages `harper-ls` supports](./language-server#Supported-Languages). Typically, if you may want to use `harper-ls` to edit Markdown files and you have [`markdown-mode`](https://jblevins.org/projects/markdown-mode) installed, you can configure it like this:
+
+```elisp title=init.el
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               '(markdown-mode . ("harper-ls" "--stdio"))))
+```
+
+## Optional Configuration
+
+Additionally, you can also configure things like which linters to use or how you want code actions to appear. Below is an example config where everything is set to their default values:
+
+```elisp title=init.el
+(setq-default eglot-workspace-configuration
+              '(:harper-ls (:userDictPath ""
+                            :fileDictPath ""
+                            :linters (:SpellCheck t
+                                      :SpelledNumbers :json-false
+                                      :AnA t
+                                      :SentenceCapitalization t
+                                      :UnclosedQuotes t
+                                      :WrongQuotes :json-false
+                                      :LongSentences t
+                                      :RepeatedWords t
+                                      :Spaces t
+                                      :Matcher t
+                                      :CorrectNumberSuffix t)
+                            :codeActions (:ForceStable :json-false)
+                            :markdown (:IgnoreLinkTitle :json-false)
+                            :diagnosticSeverity "hint"
+                            :isolateEnglish :json-false)))
+```
+
+:::note
+This example only contains some of the available linters, check out our [rules page](../rules) to view the full list.
+:::
+
+For more information on what each of these configs do, you can head over to the [configuration section](./language-server#Configuration) of our `harper-ls` documentation.
+
+## Additional Links
+
+- [Community discussion on configuring `harper-ls` for Emacs](https://github.com/Automattic/harper/discussions/150)
diff --git a/packages/web/src/routes/docs/integrations/helix/+page.md b/packages/web/src/routes/docs/integrations/helix/+page.md
@@ -1,15 +1,77 @@
 ---
-title: Helix Support
+title: Helix
 ---
 
-To use Harper in [Helix](https://helix-editor.com/), you'll need to have `harper-ls` installed.
+Our Helix integration is powered by [`harper-ls`](./language-server).
 
-Once you do, add this to you configuration:
+## Required Setup
 
-```toml
+Make sure you have [`harper-ls` installed](./language-server#Installation) on your system and available in your `PATH`.
+
+Helix supports language servers [out-of-the-box](https://docs.helix-editor.com/languages.html), but you'll still need to configure it to use `harper-ls`. First, you need to tell Helix how it should run `harper-ls`:
+
+```toml title=languages.toml
 [language-server.harper-ls]
 command = "harper-ls"
 args = ["--stdio"]
 ```
 
-Helix has [official documentation](https://github.com/helix-editor/helix/wiki/Language-Server-Configurations#harper-ls) as well.
+Then, for all the [languages `harper-ls` supports](./language-server#Supported-Languages) that you want it to be enabled for, you need to declare the following in your `languages.toml`:
+
+```toml title=languages.toml
+[[language]]
+name = "language-id"
+language-servers = ["default-servers", "harper-ls"]
+```
+
+where `language-id` is the language ID of the language you want `harper-ls` to be used for and `default-servers` are any of the [default language servers](https://docs.helix-editor.com/lang-support.html) supported by Helix that you use for that language. For example, if you want to configure it for Markdown and you use both Marksman and Markdown-Oxide, you'd end up with this:
+
+```toml title=languages.toml
+[[language]]
+name = "markdown"
+language-servers = ["marksman", "markdown-oxide", "harper-ls"]
+```
+
+You need to include the default language servers since there currently isn't a way to append a language server to the default `language-servers` list. Of course, you can also add other language servers you use before or after `harper-ls`.
+
+## Optional Configuration
+
+Additionally, you can also configure things like which linters to use or how you want code actions to appear. Below is an example config where everything is set to their default values:
+
+```toml title=languages.toml
+[language-server.harper-ls.config.harper-ls]
+userDictPath = ""
+fileDictPath = ""
+diagnosticSeverity = "hint"
+isolateEnglish = false
+
+[language-server.harper-ls.config.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
+
+[language-server.harper-ls.config.harper-ls.codeActions]
+ForceStable = false
+
+[language-server.harper-ls.config.harper-ls.markdown]
+IgnoreLinkTitle = false
+```
+
+:::note
+This example only contains some of the available linters, check out our [rules page](../rules) to view the full list.
+:::
+
+For more information on what each of these configs do, you can head over to the [configuration section](./language-server#Configuration) of our `harper-ls` documentation.
+
+## Additional Links
+
+- [Helix's official documentation on `harper-ls`](https://github.com/helix-editor/helix/wiki/Language-Server-Configurations#harper-ls)
+- [Community discussion on configuring `harper-ls` for Helix](https://github.com/Automattic/harper/discussions/135)