Documentation updates

README.md

@@ -52,7 +52,7 @@ Just make sure to read [our contribution guidelines first.](https://github.com/a
   - [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)
+- [Official Discord Server](https://discord.com/JBqcAaKrzQ)
 
 ## Huge Thanks
 

packages/web/src/routes/+page.svelte

@@ -81,16 +81,18 @@ let mobile = $derived(width < 640);
 <Section swapped={!mobile}>
 	<span slot="title">Native Everywhere</span>
 	<span slot="subtitle"
-		>Harper is both available as a <a
-			href="https://writewithharper.com/docs/integrations/language-server">language server</a
-		>, and through WebAssembly, so you can get fantastic grammar checking anywhere you work.
+		>Harper is available as a <a
+			href="/docs/integrations/language-server">language server</a
+		>, <a href="/docs/harperjs/introduction">JavaScript library</a
+		> through WebAssembly, and <a
+		href="https://crates.io/crates/harper-core">Rust crate</a
+		>, so you can get fantastic grammar checking anywhere you work.
 		<br /><br /> That said, we take extra care to make sure the
-		<a href="https://marketplace.visualstudio.com/items?itemName=elijah-potter.harper"
+		<a href="/docs/integrations/visual-studio-code"
 			>Visual Studio Code</a
-		>, Neovim,
-		<a href="https://github.com/Stef16Robbe/harper_zed">Zed</a>
+		>, <a href="/docs/integrations/neovim">Neovim</a>,
 		and
-		<a href="/docs/integrations/obsidian">Obsidian</a> integration is amazing.
+		<a href="/docs/integrations/obsidian">Obsidian</a> integrations are amazing.
 	</span>
 
 	<img

packages/web/src/routes/docs/about/+page.md

@@ -3,7 +3,7 @@ title: What Is Harper?
 ---
 
 Harper is a grammar checker designed to run anywhere there is text (so really, anywhere).
-Most Harper users are catching their mistakes in Neovim, [Obsidian](./integrations/obsidian), or Visual Studio Code.
+Most Harper users are catching their mistakes in [Neovim](./integrations/neovim), [Obsidian](./integrations/obsidian), or [Visual Studio Code](./integrations/visual-studio-code).
 
 <script>
     import Editor from "$lib/Editor.svelte"
@@ -20,6 +20,4 @@ If something is off, Harper lets you know.
 
 In a way, Harper is an error-tolerant parser for English.
 
-## How Can I Start Using Harper?
-
-We have a number of integrations available for a number of use-cases, ranging from [Obsidian for note-taking](./integrations/obsidian) to [Neovim](./integrations/neovim) or [Visual Studio Code](./integrations/visual-studio-code) for programming.
+Check out our [FAQs](./faq) to know how you can use Harper and more.

packages/web/src/routes/docs/contributors/author-a-rule/+page.md

@@ -123,7 +123,7 @@ insert_struct_rule!(AdjectiveOfA, true);
 insert_pattern_rule!(BackInTheDay, true);
 insert_struct_rule!(WordPressDotcom, true);
 insert_pattern_rule!(OutOfDate, true);
-// [svp! df:+]   insert_pattern_rule!(MyRule, true); 
+// [svp! df:+]   insert_pattern_rule!(MyRule, true);
 ```
 
 If you use a `PatternLinter`, use `insert_pattern_rule` to take advantage of Harper's aggressive caching.
@@ -208,6 +208,10 @@ Every time you want to test a change, you'll have to recompile `harper-ls` and r
 cargo build --release # Run in the monorepo to compile `harper-ls`.
 ```
 
+:::note
+This workflow only works if all you're changing is the Rust code. If your changes include updates to the VS Code extension or if you'd like to test your new rule's setting in VS Code by adding it to `package.json`, then you'd need to open the extension in an [Extension Development Host](./visual-studio-code#Running-the-Extension).
+:::
+
 ## Elevate Your Pull Request
 
 Once you're satisfied with your rule, you can go ahead and elevate your pull request to mark it as "ready for review."

packages/web/src/routes/docs/contributors/visual-studio-code/+page.md

@@ -7,34 +7,41 @@ This document details how to develop the Visual Studio Code extension locally. I
 ## 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 pick up 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.
+- VS Code can only pick up the tasks and launch configurations set in `packages/vscode-plugin/.vscode` if `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 does.
 
 ## Prerequisites
 
-- Make sure to [set up your environment](./environment).
+- Make sure to [set up your environment](./environment). Be sure to run `just setup` as the guide recommends, or at least `pnpm install`, to make sure the extension's dependencies are installed.
+- Install the [recommended extension](https://github.com/Automattic/harper/blob/master/packages/vscode-plugin/.vscode/extensions.json), [`connor4312.esbuild-problem-matchers`](https://marketplace.visualstudio.com/items?itemName=connor4312.esbuild-problem-matchers), so VS Code can understand and run esbuild tasks.
 - 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
 
+Following these steps will open the extension in a new Extension Development Host window, so you can view your changes.
+
 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
 
+You may run the following command to run the tests, this is the recommended way.
+
 ```bash
 just test-vscode
 ```
 
+### Using VS Code's Debugger
+
+You may also follow these steps to run the tests through your VS Code installation.
+
+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`.
+
 ## Packaging and Installing the Extension
 
 1. Package the extension:

packages/web/src/routes/docs/faq/+page.md

@@ -2,25 +2,40 @@
 title: Frequently Asked Questions
 ---
 
-## Is There a Chrome or Firefox Extension?
+## How Do I Use or Integrate Harper?
 
-**Short answer**: not yet.
+That depends on your use case.
+
+Do you want to use it within Obsidian? We have an [Obsidian plugin](/docs/integrations/obsidian).
+
+Do you want to use it within WordPress? We have a [WordPress plugin](/docs/integrations/wordpress).
+
+Do you want to use it within your code editor? We have documentation on how you can integrate with [Visual Studio Code and its forks](/docs/integrations/visual-studio-code), [Neovim](/docs/integrations/neovim), [Helix](/docs/integrations/helix), [Emacs](/docs/integrations/emacs), and [Zed](/docs/integrations/zed). If you're using a different code editor, then you can integrate directly with our language server, [`harper-ls`](/docs/integrations/language-server).
+
+Do you want to integrate it in your web app or your JavaScript/TypeScript codebase? You can use [`harper.js`](./harperjs/introduction).
+
+Do you want to integrate it in your Rust program or codebase? You can use [`harper-core`](https://crates.io/crates/harper-core).
 
-**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 official Harper maintainers to make an attempt in the near future.
+## What Human Languages Do You Support?
 
-If you're interested in trying to make one, let us know how it goes.
-We might be able to help.
+We currently only support English and its dialects British, American, Canadian, and Australian. Other languages are on the horizon, but we want our English support to be truly amazing before we diversify.
 
-## Why Doesn't Harper Support My Programming Language?
+## What Programming Languages Do You Support?
 
-Harper (particularly `harper-ls`) tries to support a wide variety of programming languages.
-If one is missing, it's probably because we haven't had time to get to it yet.
-We are entirely open to PRs that add support.
+For `harper-ls` and our code editor integrations, we support a wide variety of programming languages. You can view all of them over at [the `harper-ls` documentation](/docs/integrations/language-server#Supported-Languages). 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, you can use [this PR as a model for what to do](https://github.com/Automattic/harper/pull/332).
 
-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).
+For `harper.js` and those that use it under the hood like our Obsidian plugin, we support plaintext and/or Markdown.
+
+## Is There a Chrome or Firefox Extension?
+
+**Short answer**: not yet.
+
+**Long answer:** 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. However, if you're interested in trying to make one, let us know how it goes. We might be able to help.
 
 ## Where Did the Name Harper Come From?
 
 See [this blog post](https://elijahpotter.dev/articles/naming_harper).
+
+## What Do I Do If my Question Isn't Here?
+
+You can join our [Discord](https://discord.gg/JBqcAaKrzQ) and ask your questions there or you can start a discussion over at [GitHub](https://github.com/Automattic/harper/discussions).

packages/web/src/routes/docs/integrations/emacs/+page.md

@@ -16,14 +16,26 @@ Since version 29, Emacs has had native support for the Language Server Protocol
                '(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:
+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 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"))))
 ```
 
+:::note
+
+A possible gotcha you may be encountering if you don't see any diagnostics is when Eglot automatically deduces the language ID being sent to `harper-ls` based on the major mode you used. In which case, you can set the language ID to one that is supported:
+
+```elisp title=init.el
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               '((english-prose-mode :language-id "plaintext") . ("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:
@@ -46,7 +58,8 @@ Additionally, you can also configure things like which linters to use or how you
                             :codeActions (:ForceStable :json-false)
                             :markdown (:IgnoreLinkTitle :json-false)
                             :diagnosticSeverity "hint"
-                            :isolateEnglish :json-false)))
+                            :isolateEnglish :json-false
+                            :dialect "American")))
 ```
 
 :::note
@@ -55,6 +68,17 @@ This example only contains some of the available linters, check out our [rules p
 
 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.
 
+## Common Config Changes
+
+Programmers often find certain rules have too much of a hair-trigger.
+The below config is a simple cut-and-paste that gives you much fewer false-positives.
+
+```elisp title=init.el
+(setq-default eglot-workspace-configuration
+              '(:harper-ls (:linters (:SpellCheck :json-false
+                                      :SentenceCapitalization :json-false))))
+```
+
 ## Additional Links
 
 - [Community discussion on configuring `harper-ls` for Emacs](https://github.com/Automattic/harper/discussions/150)

packages/web/src/routes/docs/integrations/helix/+page.md

@@ -44,6 +44,7 @@ userDictPath = ""
 fileDictPath = ""
 diagnosticSeverity = "hint"
 isolateEnglish = false
+dialect = "American"
 
 [language-server.harper-ls.config.harper-ls.linters]
 SpellCheck = true
@@ -71,6 +72,17 @@ This example only contains some of the available linters, check out our [rules p
 
 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.
 
+## Common Config Changes
+
+Programmers often find certain rules have too much of a hair-trigger.
+The below config is a simple cut-and-paste that gives you much fewer false-positives.
+
+```toml title=languages.toml
+[language-server.harper-ls.config.harper-ls.linters]
+SpellCheck = false
+SentenceCapitalization = false
+```
+
 ## Additional Links
 
 - [Helix's official documentation on `harper-ls`](https://github.com/helix-editor/helix/wiki/Language-Server-Configurations#harper-ls)

packages/web/src/routes/docs/integrations/language-server/+page.md

@@ -121,6 +121,37 @@ We _do_ take pull requests or issues for adding words to the static dictionary.
 | `HarperAddToUserDict`  | Adds the selected word to the user dictionary              | `Add "containes" to the global dictionary.` |
 | `HarperAddToFileDict`  | Adds the selected word to a file-local dictionary          | `Add "containes" to the file dictionary.`   |
 
+## Ignore Comments
+
+`harper-ls` supports skipping comment blocks that contain any of following:
+
+- `harper:ignore`
+- `harper: ignore`
+- `spellcheck:ignore`
+- `spellcheck: ignore`
+
+So "spellcheckd" and other spelling or grammar errors will not be flagged in any of the following comments:
+
+```js
+// 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
+}
+```
+
+For CSpell compatibility, we also support these ignore comments:
+
+- `cSpell:ignore`
+- `cSpell: ignore`
+- `spell-checker:ignore`
+- `spell-checker: ignore`
+- `spellchecker:ignore`
+- `spellchecker: ignore`
+
 ## Configuration
 
 `harper-ls` expects a JSON object with a `harper-ls` key that contains your configs:

packages/web/src/routes/docs/integrations/neovim/+page.md

@@ -46,7 +46,8 @@ require('lspconfig').harper_ls.setup {
         IgnoreLinkTitle = false
       },
       diagnosticSeverity = "hint",
-      isolateEnglish = false
+      isolateEnglish = false,
+      dialect: "American"
     }
   }
 }

packages/web/src/routes/docs/integrations/visual-studio-code/+page.md

@@ -27,3 +27,7 @@ The settings below are VS Code specific. There are other settings that `harper-l
 | Setting       | Type     | Default Value | Description                                                                                                                                                 |
 | ------------- | -------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `harper.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. |
+
+## Other Features
+
+Since the extension is powered by `harper-ls`, it also supports [dictionaries](./language-server#Dictionaries), [code actions](./language-server#Code-Actions), and [ignore comments](./language-server#Ignore-Comments).

packages/web/vite.config.ts

@@ -39,8 +39,16 @@ export default defineConfig({
 				sidebar: {
 					'/docs/': [
 						{
-							title: 'About',
-							to: '/docs/about',
+							items: [
+								{
+									title: 'About',
+									to: '/docs/about',
+								},
+								{
+									title: 'FAQ',
+									to: '/docs/faq',
+								},
+							],
 						},
 						{
 							title: 'Integrations',
@@ -161,10 +169,6 @@ export default defineConfig({
 								},
 							],
 						},
-						{
-							title: 'FAQ',
-							to: '/docs/faq',
-						},
 						{
 							title: 'Rules',
 							to: '/docs/rules',