Beginner-friendly, unofficial documentation for Helix text editor | Hacker News Reader

Beginner-friendly, unofficial documentation for Helix text editor

helix-editor.vercel.app

205 pointsCuriositry68 comments

Worth mentioning that while this was very nice work by a Helix enthusiast, it was proposed as a replacement for the official docs and mostly rejected, and for good reasons IMO. An instructive discussion!

https://github.com/helix-editor/helix/pull/12127#issuecommen...

It's rarely a good idea to do a bunch of work on a big change to an open source project in a direction that has not been validated by the maintainers. Or at least, if you do, do it for your own education and don't have high expectations that it will be merged. The contributor in question had a very good attitude about it.

> It's rarely a good idea to do a bunch of work on a big change to an open source project in a direction that has not been validated by the maintainers.

While this is good advice in general, it doesn't tell the whole story in the case of this specific project. The helix maintainers have a track record of giving very slow "no"s and wasting contributor time. They encourage contributors to fix various odds and ends, until the PR has been nit picked to death, and then finally the concept is rejected. Totally backwards, good project leadership would front-load the conceptual yay-or-nay before reviewing any actual code.

I think you have it backwards in two ways:

1. While Helix dev is on the slow side, I think what you’re describing as specific to Helix is in fact the typical case in open source

2. In this case the author did a bunch of work up front and the maintainers said no almost immediately after the PR was posted

I agree they could be faster to say no, but I think part of it is that the maintainers would have to agree themselves and as far as I know they are not getting together to come to consensus about random Helix PRs every day.

Writing good docs is almost impossible, the existing ones weren’t good when I read them so I wouldn’t be so reverent about these norms or whatever. State your contribution as loudly as you want but be prepared to meet the light of reality. Also sometimes the people in charge are too stupid to understand you’re right.

The Helix devs have a very specific and unusual taste, so I would never consider PR-ing anything more than a simple bug fix.

Not all open-source projects want contributors, many are open-source for different reasons.

what do you mean by specific and unusual, out of curiosity?

Here's one way to see. Look at closed PRs with "changes requested" reviews:

https://github.com/helix-editor/helix/pulls?q=is%3Apr+is%3Ac...

> - The homepage right now is extremely lightweight and uses next to no javascript. The new design just looks like the same generic Starlight template I'm not sure we want to use a javascript framework. While it provides a lot of features, bitrot in the javascript ecosystem happens at a very fast pace (and pulls in thousands of dependencies). I have sites written both in gatsby and vuepress and between major version breaking changes and deprecations as frameworks cycle, it's a ton of work to keep up (e.g. vuepress -> vitepress/vuepress v2). Even mdbook upgrades have been a pain since we need to merge down theme updates. I'd prefer to see something simple, e.g. (https://docs.racket-lang.org/guide/). What do we do in five years when Starlight is deprecated by another framework, and Astro is several major releases ahead, with breaking changes?

This is a very valid point, and a mark of a mature developer who has been bitten by frontend churn, and wants something stable, simple, reliable, and predictable.

A while ago I made a dense cheat sheet for Helix. It's a touch out of date, but still possibly useful. https://github.com/stevenhoy/helix-cheat-sheet

Hey nice to have you here. I found your cheatsheet and printed it out a while ago :D

I'm glad you liked it. I keep meaning to update it (work and life get in the way), if the demand is there.

(edited for grammar)

Looking forward to when you might! Also have this on my wall

It’s great! How did you do it? I printed it out months ago and wondered how to do one myself

Manually, using Omnigraffle. It's not text-driven like Mermaid or Typst. I made a list of all the commands in the docs, grouped them by similarity and then created tables in Omnigraffle. OG has a very cool scale-text-and-graphics feature that allowed the boxes to re-size nicely on the page.

I learned a lot doing it, and thought others would find it useful.

So, there's no source to share, other than the OG file. It seems I have some options: 1) update it myself, or 2) let others make another (utensil has started one using Typst; it's at https://github.com/utensil/helix-cheat-sheet).

I always appreciate the work of others to make useful things, and wanted to give something back, no matter how small. Given my other commitments it will take me about a month or so to bring it up to date.

stappersg opened an issue in the repo (https://github.com/stevenhoy/helix-cheat-sheet/issues/1) - Ill post this comment there and ask for feedback.

Amazing work, Tank you. Looking forward to the update

I'd prefer a more honest tutorial. Who is this editor for? and show the kinds of problems it was designed to solve, nobody makes generalist text editors anymore and nobody needs a generalist editor. Like are you really trying to convince poets to use this? Of course not, this tutorial relies on some domain expert seeing it and mapping the functionality show in the examples to their problem.

Also the utility of these kinds of editors goes way down when you aren't doing many quick edits of arbitrary files ( which points to a larger workflow problem though perhaps unavoidable for some )

Am poet who uses helix!

Currently, I'm using VS Code with Vim keybindings (through the Neovim plugin). My workflow (C/C++/Rust) involves multiple panes open, using the lldb debugger, goto/peek definitions, CMake integration w/ active target compilation on Ctrl+Shift+B, clang format on save, LLM-powered tab-autocomplete, and IntelliSense powered by `compile_commands.json`.

Is switching to Helix worth it? Can I get more-or-less equivalent functionality with Helix?

The debugger in helix was extremely barebones last I tried, LLM integration can only be made available through custom language servers since they do not support plugins yet.

If you are interested in making a move to a terminal editor I would instead look to neovim until helix matures a bit more

I don't think Helix can currently match the C++ experience you get with VS Code.

* Debugging is rough. There's experimental DAP support, but it isn't ready to be used. I was able to set breakpoints and step through the code, but the UI for exploring variables / state while paused felt missing or was unintuitive enough that I couldn't figure it out. I use CLion for debugging.

* Goto definition works with clangd as long as your CMake setup outputs compile_commands.json, which you already do.

* Renaming symbols (variables / functions) via clangd works fine.

* Intellisense is decent, but I had to tweak clangd settings. By default, it would stop returning results after scanning a certain number of symbols, so some valid functions just didn't show up. I was using Helix for a few days before realizing this problem, it isn't obvious that you are getting an artificially constrained filtered view of your symbols via default clangd. Maybe this is a distro packaging issue though?

* The order of intellisense completions is not great. CLion is smart about surfacing relevant suggestions first. In Helix + clangd, I often get obscure symbols that obviously have nothing to do with my project or context. It's not the worst thing, but it is mildly annoying and noticeable.

* "go to error" doesn't surface errors in files that aren't open. In Helix, space D brings up workspace diagnostics, but it only shows errors for compilation units already open. This appears to be a clangd issue, as space D in other languages will show all project errors. CLion does not suffer from this problem.

* I think you can get LLM suggestions via an LSP, but I've not tried personally. Assuming it's true that you can get LLM suggestions, it's not clear to me that you can run two LSP's on the same file, so it might be a choice between clangd and an LLM LSP? Not sure.

* No integrated build support. You'll probably end up building from a terminal. I use Wezterm with a custom lua script that is invoked on a hotkey. I put a lot of thought into the build UX, and what I've done is both extremely hacky and still not good enough.

Helix is not flexible, it's uncompromising. I like it, but I think it's hard to beat CLion or vscode for C++ development.

I'd say right now, if you have a good setup already, stick with what you have.

You'll need to spend a lot of time figuring it out and yet miss many of the features.

I experimented with Helix a bit, and my experience (which uses a slightly different workflow):

* I need workspace folders. Even combined with fzf or similar tools, file navigation is nowhere as easy as in VSCode

* Debugging is important and missing

* Missing custom extensions that likely will never be ported to Helix even if there is an extension system

Isn’t the built in tutor build to interactively teach exactly what this site contains?

Does Helix have no way to go back to the last editing position when re-opening a file? Similar to: '" in vim? That is going to be a deal-breaker for me. One reason I use vim over many other options is that I jump in and out of files a lot, having to find my last position in many cases is a chore.

If you don't have one already, here's an autocmd I use for that https://gist.github.com/shorsher/93b747bf5c4209f45ef0304aa50...

Not yet in release branch, afaik

https://github.com/helix-editor/helix/issues/401

The more I think about this, the more I'm leaning towards the opinion: Being able to get back to where you were when you were last editing a file, is table stakes in a programmers editor. But Kakoune and Helix both don't seem to do it (kak has "ga", which just doesn't seem to work on either system I've tried it, both running 2025 versions. So maybe I'm wrong there. But the last thing I want to do when I edit a file is to hunt for the code or bread crumbs of where I was. I really like the direction Helix is leaning in, but it's hard to take it seriously as a code editor if I can't get back to where I was. I guess vim has just spoiled me in that regard.

Thanks for the pointer there. Last night I had Claude Code implement position saving/restore, and I've put it up at: https://github.com/linsomniac/helix-resume

I gave helix a serious shot for a week, converting shortcuts and adapting to helix's way. In the end I couldn't find any advantage to it over my vim setup. It was not plug and play it was not configuration free, it was not noticeably faster. It was just full of negatives. Little gripes like the one you mention. Vim just seems to do everything better with fewer popups and selection flashes.

Personally I find helix is basically vim with selection oriented editing borrowed from kakoune, which is fine I guess. Real kakoune has another radical idea that helix doesn’t touch though, which is its thorough unix integration. If vim is vi for the Amiga, kakoune is vim for unix, bringing things full circle.

Yeah, I gave it a very fair shot. Got pretty good at it too. But I’m back to Vim too.

Things I loved: no plugins. Native LSP integration. The pickers are a lot faster and nicer than what I can get in neovim after absolutely atrocious configs.

Things I liked: w and e selects the word. I kinda got used to that and miss it in vim now.

Things I loathed: there is no clear mental model of what will get selected on a motion. Something like selecting a paragraph (V } in vim) is replaced with a (gf) which doesn’t ever do exactly what I want.

Overall, the annoyances outweighed the benefits. I wish evil-helix all the luck. I would use it but it kinda sucks on Mac rn since you have to whitelist every library used.

I really would love to move to helix but they can be… stubborn about what gets into the core. And if you start having to go to a plugin (which isn’t even possible last I looked) to get table stakes features in, it kind of defeats the purpose of a modern batteries included modal editor. But it’s still a cool thing I’m glad exists.

> but they can be… stubborn about what gets into the core.

Yes, as an onlooker who is similarly cautious about moving to helix, I consider this to be a major risk factor. I've watched the maintainers waste dozens of hours of contributors' time, and leave the project with no improvement afterwards. I would actively warn against anyone trying to contribute to the project. The maintainers simply don't know how to run an open source project, and it's unlikely you will be able to accomplish anything. It's fine for a project to not accept contributions, and if you don't have the skillset to leverage contributor labor, then it's better to be upfront about it.

That being said, I hope they figure out the plugin system, or someone forks the project to add the missing table stakes features.

This is what killed all the momentum that Elm had at one point. While that's a language and not an entire editor, it does serve as an illustrative example of being far too strict about accepting changes to core.

For projects without funding, there is typically a trade off between a polished coherent product, which means saying no a lot, and a bloated product that has enough maintainer bandwidth to stay around. The second means saying yes to things which may not make the product better, in order for newcomers to feel bought into the project and want to maintain it.

For something like an editor, where whole features can be turned off by default, there's quite a bit of leeway to add bloat and get newcomers to buy in, without actually making the product worse.

For a programming language, a feature in the language has to be used by everyone. So the leadership has to say no a lot to keep the language high quality, and that makes it hard to get newcomers to buy in.

Unfortunately you can't have it both ways without paying people to maintain the project. Elm was good because the leadership said no...often. It's dead because the leadership said no so often that no one wanted to help maintain it. No one is going to waste their free time working on a project that won't accept their ideas, nor should they.

A language like Go doesn't have this trade off. If the Go leadership rejects a google employee's proposed language change, the employee still has to do maintenance chores as directed to keep their job.

> The maintainers simply don't know how to run an open source project

Can you explain why you feel this way? From an outsider’s perspective, Helix seems like an impressive piece of software with a growing community. I don’t see what the maintainers are doing so wrong

Being able to build high quality software alone is a distinct skill from being able to make a group of engineers productive. Neither are soft skills, it comes down to how the software is architected and how well you can produce, understand, and communicate designs with the other collaborators.

I do consider helix to be an impressive piece of software, and I agree that the user base is growing, not necessarily the set of effective maintainers though. The maintainers don't seem to have any aptitude for coordinating engineering effort. That would be fine, if they were honest and direct about it. SQLite is a project which does not accept contributions, I think helix should do the same.

Put differently, I don't expect the large community to have a meaningfully positive effect on the quality of the software, because the maintainers have not demonstrated the competency to effectively utilize that labor. I expect helix to continue slowly improving at whatever rate the maintainers can make important changes themselves.

It’s a ridiculous and inflammatory claim to make about a clearly successful project with an enthusiastic community of users who love it. The maintainers have day jobs and have a clear and narrow vision that they don’t want to mess up by carelessly expanding the pool of maintainers. That is the entire explanation!

> That being said, I hope they figure out the plugin system, or someone forks the project to add the missing table stakes features.

They decided on an obscure Lisp flavor as the language (instead of WASM), so I don't hold my breath for a powerful plugin system, more like slightly more convenient configuration language.

Yes, if only we would have an example of an editor with a “obscure lisp flavor” and a powerful plugin system, unlike WASM!

It’s not even an obscure Lisp flavor. It’s Scheme. You’re getting thrown off by the fact that they need their own embeddable interpreter for it written in Rust.

https://github.com/mattwparas/steel

I actually moved from VS Code to helix and happily used it exclusively for about 4-5 months, at that point I had list list of things I really wanted in my editor. I took that list to neovim and haven’t looked back!

I really hope to be able to use helix again in the future though, there was a speed advantage in helix and less janky window management.

But for me to do that they might have to allow full vim motions as well

The latest neovim is a bear to install unless you have something newer than Ubuntu 22.

Every time I've used Ubuntu their packages have seemed pretty out of date across the board. Is there something extra Neovim is doing here to make that worse?

It needs a newer version of glibc, but much of the OS relies on this library, so creating a conflict can cause much mayhem.

you want a stable os where everything is frozen at 3 years ago, except you don't want it frozen at 3 years ago...

I think so too, a lot of my friends have told me they had a great experience with helix, but vim keybinds are rooted too deep, and it's also the sunk cost of having built the config over an entire year. But, I think I would give it a try sparingly.

There are a number of reasons I use Helix but one of them is the maintainers’ approach to managing development of the editor and accepting (or not) contributions.

For me, slow and opinionated is a feature, not a bug.

Can someone explain to me the concept being Helix? I never got it.

From a casual reading, it looks like vim with no text objects and no support for ed commands so basically vim stripped of two of the main things that makes it good.

I understand it wants to be a more rational successor but while I got how sam tried to achieve that by breaking the limit on line editing, making clever use of mouse selections and switching ed for a new non line limited syntax (how I wish ssam had replaced sed), I don’t get the Helix value proposition.

I used vim for about twenty years, and I'm mostly happy having moved from neovim to helix.

The main thing I miss in helix is solid debugging support and slime style repl support - but I never had that working in vim.

The other thing I'm missing in ruby is "go-to definition" automatically working with dependencies, allowing to go to the source code by "opening" gems - tpope has/had some amazing stuff for ruby development with vim.

That said - I like how helix is more discoverable (pop up context menu), has sane/great defaults and out of the box experience - and I like the select-apply or subject-verb and multi cursor workflow better than vim verb-subject flow.

I recommend trying to go through the tutorial and see if fits.

I'm hoping plugin support will open the door to some improved go-to-definiton support - I'd love to be able to go "up" to edit/view dependencies be that libc source code, java, rust crates etc.

I keep meaning to get back into Helix, I'm super close to setting up an "vi=hx" alias. I had Claude make me a cheat sheet, but I haven't gone over it, here it is if it helps anyone: https://box.linsomniac.com/HelixCheatSheet.pdf

Your cheatsheet has some hallucinations in there. For example there is no :git command

you can do "! git status" etc

There is some other integration for git like SPACE + g to see file changes for example

Thanks for pointing that out, I'm planning on switching to helix this week and seeing how it goes, and once I do I'll dig deeper into a cheat sheet. There's another comment on this thread that has a cheatsheet that is probably a better place to start, but I had never run across it before: https://github.com/stevenhoy/helix-cheat-sheet

Heh, "vi=hx" was exactly how I forced myself to spend a week in helix. Just go for it

I guess Helix is made to have appeal for Vim users. At the same time, times change and usually people expect less step learning curve (including myself!).

I would really appreciate visible-by-default hints, alike in Linear.app. Then, learning shortcuts becomes organic, rather one need to keep tutorial open, or have a cheatsheet of some sorts.

For what it's worth, this is actually one of the strong-points of helix. Many of the key-bindings display an unobtrusive list of follow-up actions that close without any lag if you already know what you're looking for. It's worth trying specifically because of how much effort has gone into being easier to pick up and get started with than something like vanilla vim.

Can any Helix users share how the muscle memory from vim is working out? I’d really like to give it a go but I’m worried I’ll pollute my memory of basic vim commands. I’m bad enough remembering cut/copy/paste keyboard shortcuts in different OS/applications.

> I’m bad enough remembering cut/copy/paste keyboard shortcuts in different OS/applications.

Change them to be the same! It's indeed a waste to have a difference for such fundamental keybinds

Same with Helix - there is a vim layout out there, no need to use a different set (unless, of course, you can use something better, but then you should also use it in vim)

There’s also a fork called evil helix that uses more VIM-like bindings: https://github.com/usagi-flow/evil-helix

Helix has been my daily driver for a few years now, and it’s extremely familiar if you’re coming from the LazyVim setup for NeoVim. I make a few mistakes here and there if I have to use tools with just basic VI binds, but you learn to juggle them both.

The config is very well documented and it would be simple to rebind things too.

Hope you give it a shot!

It's mostly worked out cleanly, there's a ton of re-use of vim-isms. Now I just can't use vim anymore.

I keep trying Helix but just got hit by wq freeze issue, opened since 2022, so I wonder sometimes if its ready.

https://github.com/helix-editor/helix/issues/2059

Great to see so much Helix content on HN lately. Excited to give it a try!

It's the first editor since probably sublime text that I've genuinely enjoyed. Useful without any configuration, and very easy to get a productive environment.

There's a few rough edges that I'm trying to work through. I've been able to solve my "open in X" like key bindings. But I have yet to get things like "run test for current method". That's probably the biggest pain point I've had so far

Many complain here about the helix maintainers pace and PR rejection rate. I embrace it. It’s opinionated software developed in the open and you can fork any time. I prefer this model of strict high quality governance and a “no” as default to keep their vision clear.

Who doesn't like high quality! But in reality many high quality contributions are rejected, so all you're left with is "opinionated" where the opinion doesn't match yours

But you can always fork when you have different opinions or write your own thing. SQLite is governed in the same way.

Of course you can't, that's a common open source fantasy, in reality you wouldn't have enough lifetimes to improve quality and maintain changes in every app you use, that's why defaults/config flexibility/rejection of good ideas/core vs extensions etc. are important and discussed and can't be papered over with a "but fork"

your descriptions of what the j and k keys do in normal mode are reversed: j moves the cursor one line BELOW and k moves the cursor one line ABOVE.

Reply on news.ycombinator.com