docs: update integrations section #755

mcecode · 2025-02-23T16:02:20Z

Issues

Not an issue, but a discussion on #710.

Description

Rearrange integrations section's navigation (language server which powers editor integrations > editors with official plugins > editors that directly integrate with harper-ls > editors with third-party/community plugins)
Transfer VS Code readme info to official docs
Transfer VS Code development guide to official docs
Remove non-Neovim specific installation methods in the Neovim page
Transfer the configuration section explanations from the Neovim page to a new configuration section in the language server page
Add link to language server installation instructions and sample config in the Helix page
Add link to language server installation instructions and sample config in the Emacs page
Add code actions section in language server page

Note: I removed the "Copy Default Config to Clipboard" button in the Neovim page for now, but I'll try to bring it back in another PR so this one can focus on the docs' contents rather than functionality.

How Has This Been Tested?

Using Harper in VS Code
Using just dev-web and viewing the results in my browser

Checklist

I have performed a self-review of my own code
I have added tests to cover my changes

elijah-potter · 2025-02-26T18:31:43Z

Note: I removed the "Copy Default Config to Clipboard" button in the Neovim page for now, but I'll try to bring it back in another PR so this one can focus on the docs' contents rather than functionality.

That button only existed because SveltePress couldn't render code at runtime. I believe their upcoming release will be able to. If that happens before you're done with this PR, it might be worth swapping the button over to a rendered view.

Update/fix dictionary locations based on `dirs-rs` docs.

mcecode · 2025-03-02T13:27:53Z

I think this is ready for review. I'd like to get some feedback in case I made a mistake or if there's something I missed.

@elijah-potter, for everything but especially the harper-ls and Neovim pages
@hippietrail, for the VS Code pages and also for the overall grammar and such
@ficcdaf, for the Helix page
@anarcat, for the Emacs page, sorry for the tag out of nowhere but the info you provided in emacs configuration? #150 really helped me write this page, so I'd like your feedback, especially when it comes to the example configs I provided since I don't know anything about Emacs or Lisp. You can just view the Markdown here so you don't have to clone or build anything.

elijah-potter · 2025-03-03T21:26:12Z

This is some truly gorgeous work @mcecode. Everything looks good to me. I'll wait until some others have a chance to review it before merging.

ficcdaf

On the Helix integration:

I think it would be better to get rid of the Installation section and instead begin with a Required Setup section. This section should say you need harper-ls available on your system path, show how to create the harper-ls language server inside languages.toml (you have these already), but also mention that you need to explicitly enable harper for any languages/filetypes you want it to run on, with an example of how to do that.

I expand on what I mean by this in comments on the file itself. Please let me know if you're unclear about it.

What's left of the configuration section, in my opinion you could rename to Optional Configuration. This way, it's immediately clear to the user what's required in order for harper to work, and what's optional for them to tweak to their liking.

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

Co-authored-by: ficcdaf <[email protected]>

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

ficcdaf · 2025-03-04T04:47:13Z

It looks great! The Helix page is much, much clearer now. Your explanation is very good!

mcecode · 2025-03-04T04:50:37Z

It looks great! The Helix page is much, much clearer now. Your explanation is very good!

Thanks for the help @ficcdaf! Your suggestions also helped me improve the Neovim and Emacs pages in using "Required Setup" and "Optional Configuration" sections rather than "Installation" and "Configuration" sections.

Co-authored-by: ficcdaf <[email protected]>

ficcdaf · 2025-03-04T07:14:41Z

Glad to help :) I have no more comments, it all looks good from my end. But I've only checked the Helix page. Thanks for the work! I think this will help people a lot in getting started with harper.

I saw [this comment](Automattic#722 (comment)), which indicated this was missing.

mcecode · 2025-03-06T05:53:00Z

Hi @elijah-potter, I think this can merged now since some time has passed since I asked for feedback and at least you and Daniel have approved the updates. If needed, we can just add further clarifications in subsequent PRs. It'd also be nice to have the docs updated for the new release yesterday.

anarcat

lgtm, in general, but since you asked for my advice, i have suggestions :)

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

anarcat · 2025-03-06T15:57:08Z

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

+```elisp title=init.el
+(with-eval-after-load 'eglot
+  (add-to-list 'eglot-server-programs
+               '(major-mode . ("harper-ls" "--stdio"))))


major-mode is weird here, just use an actual mode:

Suggested change

'(major-mode . ("harper-ls" "--stdio"))))

'(text-mode . ("harper-ls" "--stdio"))))

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

ficcdaf · 2025-03-06T16:28:12Z

lgtm, in general, but since you asked for my advice, i have suggestions :)

I can't comment on the Lisp since I've never used emacs myself, but in general I agree that it's better to include a shorter example that still communicates the gist of how to configure things, with less risk of the example being outdated. My biggest pet peeve is when examples are outdated and I can't copy paste them. So good catch 🙂

ficcdaf · 2025-03-06T16:28:55Z

lgtm, in general, but since you asked for my advice, i have suggestions :)

Sorry what does igtm mean?

anarcat · 2025-03-06T17:08:40Z

Sorry what does igtm mean?

oh, sorry for the acronym, it means "Looks Good To Me"

Co-authored-by: anarcat <[email protected]>

mcecode · 2025-03-07T02:57:13Z

Sorry I wasn't online when you gave your suggestions @anarcat. Thanks for the review! I'm glad I didn't make many mistakes, especially in my Lisp syntax :)

Just to chime in about the sample config possibly becoming outdated that you and Daniel pointed out, I don't think any of the configs shown there will be removed nor will their defaults change any time soon. Harper has been moving quite fast with new integrations and linters being added often, but those have stayed the way they are since they were added. So I think users will be safe to copy paste it without it bit-rotting for quite a while.

Edit: I need to correct myself since it totally slipped my mind that we just had a breaking change on config keys last week with 0.23.0. So my statement that "those have stayed the way they are since they were added" is wrong. However, I stand by my statement that they likely won't be changing any time soon because that breaking change was to standardize key casing not to remove anything or change defaults, and since they've been standardized, it's likely these keys will stay the way they are.

ficcdaf · 2025-03-07T19:49:29Z

Funny enough, my PR adding a default Harper configuration to Helix just got merged. However Helix only does a release like a couple times a year so I don't think we need to update these docs anytime soon 😜

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [Automattic/harper/harper-ls](https://github.com/Automattic/harper) | minor | `v0.24.0` -> `v0.26.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>Automattic/harper (Automattic/harper/harper-ls)</summary> ### [`v0.26.0`](https://github.com/Automattic/harper/releases/tag/v0.26.0) [Compare Source](Automattic/harper@v0.25.1...v0.26.0) #### What's Changed - docs: fix user dictionary by [@kit494way](https://github.com/kit494way) in Automattic/harper#893 - feat: mask out comments beginning with spellchecker:ignore by [@grantlemons](https://github.com/grantlemons) in Automattic/harper#861 - feat(harper.js): export both binary and inlinedBinary for different runtimes by [@Asuka109](https://github.com/Asuka109) in Automattic/harper#607 - feat: linter for "as far back as" to replace "as early back as" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#889 - feat: flag "explanation mark/point" instead of "exclamation" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#895 - feat: correct "in anyway" to "in any way" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#894 - build(deps): bump [@babel/helpers](https://github.com/babel/helpers) from 7.26.9 to 7.26.10 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#899 - fix: two spelling mistakes based on homophones by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#886 - feat: allow blank lines and comments in `dictionary.dict` by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#756 - docs: fix typo [#906](Automattic/harper#906) by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#912 - hotfix(core): properly store spans in `PatternLinter` cache by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#926 - Dictionary curation 2025 03 12 by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#902 - Dialect prototyping by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#925 - feat: insert newline automatically in `just addnoun` by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#931 - docs: fix 3 grammar mistakes by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#933 - feat: linter for "each and everyone" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#923 - feat: expand the "get rid off" lint to cover "get ride of" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#900 - fix(vscode-plugin): ignore non-existent ".git" files, support untitled/unsaved files on VS Code by [@kiding](https://github.com/kiding) in Automattic/harper#927 - feat(core): improve assertion to allow overlapping suggestions by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#935 - build(deps): bump [@wordpress/editor](https://github.com/wordpress/editor) from 14.19.0 to 14.20.0 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#915 - build(deps): bump indexmap from 2.7.1 to 2.8.0 by [@dependabot](https://github.com/dependabot) in Automattic/harper#921 - build(deps): bump tokio from 1.43.0 to 1.44.1 by [@dependabot](https://github.com/dependabot) in Automattic/harper#919 - build(deps-dev): bump [@types/node](https://github.com/types/node) from 22.13.9 to 22.13.10 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#913 - build(deps): bump foldhash from 0.1.4 to 0.1.5 by [@dependabot](https://github.com/dependabot) in Automattic/harper#917 - feat: correct "along time" to "a long time" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#910 - Add -able affix to open (openable) by [@claydugo](https://github.com/claydugo) in Automattic/harper#930 - docs: mention hidden library dependencies by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#943 - feat(core): create new test assertion for `nth` suggestion results by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#942 - build: migrate to pnpm workspace & biome by [@Asuka109](https://github.com/Asuka109) in Automattic/harper#924 - build(deps): bump serde from 1.0.218 to 1.0.219 by [@dependabot](https://github.com/dependabot) in Automattic/harper#920 - build(deps): bump clap from 4.5.31 to 4.5.32 by [@dependabot](https://github.com/dependabot) in Automattic/harper#946 - Web improvements by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#944 - feat: ignore shebang lines by [@holmanb](https://github.com/holmanb) in Automattic/harper#947 - feat(web): add mask-image to header by [@Asuka109](https://github.com/Asuka109) in Automattic/harper#951 - fix(core): reduce ambiguity for `AvoidContraction` by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#941 - chore: add comments describing major sections by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#952 #### New Contributors - [@kit494way](https://github.com/kit494way) made their first contribution in Automattic/harper#893 - [@holmanb](https://github.com/holmanb) made their first contribution in Automattic/harper#947 **Full Changelog**: Automattic/harper@v0.25.1...v0.26.0 ### [`v0.25.1`](https://github.com/Automattic/harper/releases/tag/v0.25.1) [Compare Source](Automattic/harper@v0.25.0...v0.25.1) #### What's Changed - docs(ls): give example config that disables `sentence_capitalization` by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#879 - fix(core): indexing problem in Regexish work by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#883 - Just getforms improvements by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#862 - Dictionary curation 2025 03 11 by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#884 - fix(core): insert paragraph breaks after code blocks by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#882 **Full Changelog**: Automattic/harper@v0.25.0...v0.25.1 ### [`v0.25.0`](https://github.com/Automattic/harper/releases/tag/v0.25.0) [Compare Source](Automattic/harper@v0.24.0...v0.25.0) #### What's Changed - docs: update integrations section by [@mcecode](https://github.com/mcecode) in Automattic/harper#755 - Typst Corrections by [@grantlemons](https://github.com/grantlemons) in Automattic/harper#442 - refactor: add comments to `just addnoun` and tweak logic by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#605 - feat: implements [#841](Automattic/harper#841) by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#842 - Add WordPress Plugin Documentation and Demo by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#838 - feat: add `just newest-dict-changes` by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#701 - Spellcheck improvements by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#844 - fix: add missing "gotten rid off" to other "rid off" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#840 - Rules page improvements by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#843 - build(deps): bump axios from 1.8.1 to 1.8.2 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#845 - Regexish by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#669 - fix: fall back to `grep` when `rg` is not available by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#848 - feat: flag "monumentous" and offer "momentous" and "monumental" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#864 - build(deps-dev): bump svelte-check from 4.1.4 to 4.1.5 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#874 - build(deps): bump typst-syntax from 0.13.0 to 0.13.1 by [@dependabot](https://github.com/dependabot) in Automattic/harper#867 - build(deps-dev): bump typescript from 5.7.3 to 5.8.2 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#871 - build(deps-dev): bump autoprefixer from 10.4.20 to 10.4.21 in /packages by [@dependabot](https://github.com/dependabot) in Automattic/harper#873 - Dictionary curation 2025 03 08 by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#860 - feat: add many variants of "change of tact"->"tack" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#852 - feat: implement [#525](Automattic/harper#525) (worse/worst confusion) by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#856 - build(deps): bump cached from 0.54.0 to 0.55.1 by [@dependabot](https://github.com/dependabot) in Automattic/harper#868 - build(deps): bump anyhow from 1.0.96 to 1.0.97 by [@dependabot](https://github.com/dependabot) in Automattic/harper#865 - Build against an older GLIBC version by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#877 - Cache busting by [@elijah-potter](https://github.com/elijah-potter) in Automattic/harper#876 - build(deps): bump thiserror from 2.0.11 to 2.0.12 by [@dependabot](https://github.com/dependabot) in Automattic/harper#866 - build(deps): bump serde_json from 1.0.139 to 1.0.140 by [@dependabot](https://github.com/dependabot) in Automattic/harper#869 - feat: add a lint to correct "in of itself" to "in and of itself" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#863 - feat: implement "ticking time clock" by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#851 - feat: implements [#746](Automattic/harper#746) by [@hippietrail](https://github.com/hippietrail) in Automattic/harper#855 - feat(dict): added words to dictionary by [@ficcdaf](https://github.com/ficcdaf) in Automattic/harper#847 - fix: Ignore hex codes inside rgb function calls by [@grantlemons](https://github.com/grantlemons) in Automattic/harper#857 - feat: Added Linux musl compilations by [@kiding](https://github.com/kiding) in Automattic/harper#878 #### New Contributors - [@kiding](https://github.com/kiding) made their first contribution in Automattic/harper#878 **Full Changelog**: Automattic/harper@v0.24.0...v0.25.0 </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

mcecode force-pushed the integration-docs branch from 6bc54d8 to 9b75d36 Compare February 26, 2025 04:44

elijah-potter mentioned this pull request Feb 27, 2025

Contradiction with some WordPress PHPCS coding standards #794

Closed

mcecode added 7 commits February 28, 2025 10:47

docs(vscode): transfer info from readme to official docs

040bb51

docs(vscode): transfer development guide to official docs

7f80103

docs: rearrange integrations section

c4ae9f1

docs(neovim): remove non-neovim specific installation methods

24c5834

docs(ls): transfer config docs from neovim page + some updates/fixes

2b0ee60

Update/fix dictionary locations based on `dirs-rs` docs.

docs(helix): update page + some fixes in other pages

ebdfafb

docs(emacs): update page + remove unneeded links

cbc8191

mcecode force-pushed the integration-docs branch from 7ab7e70 to cbc8191 Compare February 28, 2025 09:31

mcecode added 7 commits March 2, 2025 18:33

docs(ls): add code actions section

eb340ea

docs(neovim): minor page updates + fixes in other pages

eaf8271

docs(vscode): minor additions and clarifications

28e6d2f

docs(ls): rearrangement and minor updates to installation section

6660a04

docs(readme): update links

0cab4db

docs(zed): update page

f9c6f83

docs: final updates and corrections

aad2f16

mcecode marked this pull request as ready for review March 2, 2025 13:27

mcecode requested a review from elijah-potter March 2, 2025 13:28

ficcdaf suggested changes Mar 3, 2025

View reviewed changes

packages/web/src/routes/docs/integrations/helix/+page.md Outdated Show resolved Hide resolved

packages/web/src/routes/docs/integrations/helix/+page.md Outdated Show resolved Hide resolved

mcecode and others added 3 commits March 4, 2025 12:02

docs(helix): improve and add missing required steps for setup

eb81475

Co-authored-by: ficcdaf <[email protected]>

docs(emacs): improve page

a33f97d

docs(neovim): improve page

b1854d1

ficcdaf reviewed Mar 4, 2025

View reviewed changes

packages/web/src/routes/docs/integrations/helix/+page.md Outdated Show resolved Hide resolved

docs: fix nitpick

df13430

Co-authored-by: ficcdaf <[email protected]>

Merge branch 'master' into integration-docs

5fc3835

elijah-potter approved these changes Mar 4, 2025

View reviewed changes

docs: add --locked

ddd9fe0

I saw [this comment](Automattic#722 (comment)), which indicated this was missing.

ficcdaf approved these changes Mar 5, 2025

View reviewed changes

anarcat reviewed Mar 6, 2025

View reviewed changes

docs: minor edits

8abfb4e

Co-authored-by: anarcat <[email protected]>

elijah-potter merged commit c9a2efd into Automattic:master Mar 6, 2025
18 checks passed

mcecode deleted the integration-docs branch March 7, 2025 02:57

mcecode mentioned this pull request Mar 7, 2025

Add WordPress Plugin Documentation and Demo #838

Merged

2 tasks

	'(major-mode . ("harper-ls" "--stdio"))))
	'(text-mode . ("harper-ls" "--stdio"))))

docs: update integrations section #755

docs: update integrations section #755

Uh oh!

Conversation

mcecode commented Feb 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Issues

Description

How Has This Been Tested?

Checklist

Uh oh!

elijah-potter commented Feb 26, 2025

Uh oh!

mcecode commented Mar 2, 2025

Uh oh!

elijah-potter commented Mar 3, 2025

Uh oh!

ficcdaf left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

On the Helix integration:

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ficcdaf commented Mar 4, 2025

Uh oh!

mcecode commented Mar 4, 2025

Uh oh!

ficcdaf commented Mar 4, 2025

Uh oh!

mcecode commented Mar 6, 2025

Uh oh!

anarcat left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

anarcat Mar 6, 2025

Choose a reason for hiding this comment

Uh oh!

elijah-potter Mar 6, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

ficcdaf commented Mar 6, 2025

Uh oh!

ficcdaf commented Mar 6, 2025

Uh oh!

anarcat commented Mar 6, 2025

Uh oh!

Uh oh!

mcecode commented Mar 7, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ficcdaf commented Mar 7, 2025

Uh oh!

Uh oh!

mcecode commented Feb 23, 2025 •

edited

Loading

ficcdaf left a comment •

edited

Loading

mcecode commented Mar 7, 2025 •

edited

Loading