🧬◆ƒ Helix modiƒew keymap — Design overview

map the most frequent commands to the best keys; replace (hold) modifiers with (tap) key chords

Table of contents

• Overview
• Major modes
  • Normal
  • Insert
  • Select
• Minor modes
  • GoTo
  • Space
  • View
  • Match
  • Window
  • Unimpaired
• Install
• Misc

🔗 Overview

This is a draft of the modiƒew keymap for the Helix text editor that tries to break the chains ⛓ of keycap-based mnemonics¹ like f for find and instead maps most frequent commands to the best keys, so 👆🏻² (f in QWERTY) moves forward by a word instead of executing find
It also attempts to convert most of the commands requiring modifiers into a chainable key sequence, hence its name: "few modifiers based on frequency" (ƒ for frequency) or modiƒew or ◆ƒ

This keymap is based on a dumb standard staggered keyboard design, so if you use a better one with a thumb 👍🏻👍 key cluster, you might want to move some of the more frequent commands there instead. The config file is based on the standard US-based QWERTY layout³, though this document supports multiple layouts via buttons at the bottom of this overview

It's inspired by the Emacs: Xah Fly Keys and uses Xah Lee's data on Emacs command frequencies, but is trying to outlfy the fly master :) by being more consistent in applying the basic frequent→best principle⁴

Below is a summary of some of the design decisions followed up by detailed keymap Cheat Sheets for the various modes:

• ⌂ Home keys are safe: all 8 of the home keys are movement commands, so to modify a buffer your fingers need to leave ⌂!
• Insert mode has a copy of most of Normal mode commands (from key and ⇧key) on the same keys, but with an extra ⌥ — no need to switch modes for just a single command!
• Space mode converts most of the commands requiring modifiers into a chainable key sequence with a "leader" key Space as the easiest to press. Its main layer mostly consists of commands that were assigned to ⎈ or ⇧ in the Normal mode, though via additional submodes any other command can also be chained (and if this feature request is implemented, this approach could also work nicely with repeatable commands that would not close the menu dialog command list upon execution). Its ⇧ is mostly unused except for occasional shift of Normal mode's ⎇⇧ commands
• Differentiate between repeatable and single-press paired keybinds (left/right, back/forward, earlier/later etc.)
  • Repeatable keybinds should be on separate adjacent keys (just like ◀▶) instead of being on the same key with the second operation behind a ⇧’ed status, so char/word/line-based movements and in-/decrement are together rather than being on separate rows by default. This greatly simplifies going back and forth:
    • Strongest non-thumb fingers on the right hand:
      move by line 👆🏻down/🖕🏻up j▼ k▲
    • Strongest non-thumb fingers on the left hand:
      move by word 👆left/🖕right d🢔ω fω🢖
    • Rest of the home row on the right for the next most frequent commands:
      move by char 💍left/🤙🏻right l◀ ;▶
    • Repeat the 👆🏻down/🖕🏻up right hand mnemonic:
      • for the less frequent commands: decrement/increment object (number) under cursor ⎈m⊖ ⎈,⊕
      • in the lower row: move half page down/up m⤈ ,⤉
      • for the minor modes: (in ☰👁 View mode) u🗔⭳ i🗔⭱
    • Repeat the 💍left/🤙🏻right right hand mnemonic in the lower row: select previous/next search match .🢔◎ /◎🢖 (broken pending fixing this issue, at the moment requires ⇧)
    • Repeat the 👆left/🖕right left hand mnemonic for jumplist ←→ navigation 3⎗̡ 4⎘̡ (requires ⌥ pending feature)
    • Undo/redo isn't yet fully optimized in this way (they are on adjacent y↷ u⎌ , but on the same finger and in reverse order), some frequency data on the other Helix top row commands would help
  • Single-press paired keybinds can remain with the opposite direction ⇧’ed, e.g.,:
    • a⭰ move to the beginning of a line
    • ⇧a⭲ move to the end of a line
• It's ok to use (or even hold😲) ⌥ when you don't need to move by word (like in the Ⓢ Select mode), so the multi-cursor selection/manipulation is done with ⌥+cursor:
  • select down/up ⎇j🠷 ⎇k🠵 (copy_selection_on_next_line/copy_selection_on_prev_line)
  • shift selection back/forward ⎇m⟲ ⎇,⟳ (rotate_selections_backward/rotate_selections_forward)
  • quick selection correction without releasing the modifier: "soft undo" once ⎇uᵡ and all ⎇iᵡ∀ (remove_primary_selection/keep_primary_selection)
• Bonus: the Cut/Copy/Paste commands' frequencies seem to allow having them together under 💍🖕👆 left hand bottom row with the common xcv, though Undo is too frequent to be left at a 🤙z (however, with ⎈ they all maintain the zxcv compatibility) ⁵
• Turn h into a combo ⌫/⌦ key
• (lacking sufficient frequency data) Group various inserts together:
  i⁁⤸ o⤹⎀ to insert/append and
  ⇧i⭡␤ ⇧o⭣␤ to open_below/open_above (prepend_to_line/append_to_line are removed as there is a standalone command to move to the beginning of a line, so a⭰ ⇧i⁁⤸ is easier than the old i⁁⭰ )
• Add a few keybinds to make it similar to non-modal editors to help with transition
  • ⏎⭣␤ ⇧⏎⭡␤ Insert a new line below/above (open_below/open_above)
  • ⎈a∀▋ Select all
  • ⎈o☰␜ Open file_picker
  • ⎈s Save
  • ⎈z⎌ / ⎈y↷ Undo/Redo
  • ⎈xᵡ Cut (yank_main_selection_to_clipboard, delete_selection)
  • ⎈c Copy (yank_main_selection_to_clipboard)
  • ⎈v⤹ Paste (paste_clipboard_after)
  • ⌥/⎈+⌫/⌦ to delete a w/Word left/right
  • ⎈⇞/⇟ to navigate files (goto_previous_buffer/goto_next_buffer)
• ⚠ (lacking sufficient frequency data) little optimization was applied to the top vs. bottom row placement of commands
• ⚠ commands bound to 1–0 keys don't work pending implementation of this feature request, use mod1–0

Below are modiƒew Cheat Sheets for the various major and minor "modes" in an html format to make it easier to copy/search for an icon here and in the config file since not all icons are obvious enough, but also as separate images as well as links to Keyboard Layout Editor so you could adjust the cheat sheet to your modified keymap

A few tips:

• ⚠ Cheat sheets are best used in a supporting role after you have some basic familiarity with the config, so you might want to start learning by reading through the config's sections, e.g.:

  • Open config section #Ⓝ Move in Normal mode
  • Open normal mode cheat sheet side-by-side
  • Read the config and compare to the visual cheat sheet

  Later if you need to look up just a single icon/button you can use tooltips by hovering over a button or pressing ⇧KEY⁶

• You can also load a page with just the cheat sheets using these links

• ☰ is a menu icon, ⬩ beginning (⤞ to the next beginning), ❘ end (⭲ to the next end)

(or load a page with a given layout by including its name as a url #hash #qwerty #dvorak #colemak #colemak_dh #workman #neo2 #asset )

🔗 Major modes

🔗 Normal Ⓝ

@KeyboardLayoutEditor, image, config

🔗 Insert ⓘ

@KeyboardLayoutEditor, image, config

🔗 Select Ⓢ

@KeyboardLayoutEditor, image, config. Only commands that differ from Normal mode are shown, the rest are copied

🔗 Minor modes

🔗 GoTo ⮊

@KeyboardLayoutEditor, image, config

🔗 Space ␠

@KeyboardLayoutEditor, image, config. Note that modifiers are replaced with sub-modes since Space mode strives to use sequential key presses instead of key combos. Also, not all actions are yet implemented in Helix

🔗 View 👁

@KeyboardLayoutEditor, image, config

🔗 Match 🧩

@KeyboardLayoutEditor, image, config

🔗 Window 🗔

@KeyboardLayoutEditor, image, config

🔗 ⧛ Unimpaired ⧚

@KeyboardLayoutEditor, image, config

🔗 Install

1. Simple, but inflexible: copy the content of the modiƒew config keymap file to your own Helix ~/.config/helix/config.toml below your [editor] section

2. More complicated, but more flexible (makes it easier to change)

   • install chezmoi config file manager
   • copy all template files from modifew/src to your ~/.local/share/chezmoi/private_dot_config/helix folder
   • replace theme and [editor] sections of the Editor.toml.tmpl file with your preferred settings
   • build the actual full Helix config with chezmoi apply -v --interactive:
     • via the default modify_config.toml.tmpl (requires Python with tomlkit installed) that allows you to remap Helix to alternative keyboard layout (non-QWERTY or non-Latin; see instructions within that file)
     • or via the QWERTY-only config without any Python dependencies by renaming config_src.toml.tmpl to config.toml.tmpl and deleting modify_config.toml.tmpl

   Now you can edit individual template files for each major/minor mode and build the config with chezmoi instead of drowning in one huge config. You can also add a single line to include repeated minor modes in various major modes (and even pass different keybinds as input parameters to those templates) instead of having to copy&paste them manually on every single change!

🔗 Misc

Direct links to pages with only the cheat sheets (custom layouts in a #hash also work):

¹ re. mnemonics: in such a complex keybind system such as Helix's I don't find them all that useful as they don't offer intuitive predictability due to said complexity since there are several alternatives to most of the keys, e.g., should c stand for Cut/Copy/Change/Collapse/Comment/Char/Command/Case/...?

² fingers are denoted with emojis: left‹🤙💍🖕☝️👍 and 👍🏻👆🏻🖕🏻💍🤙🏻›right

³ hopefully Helix will introduce a way to translate keycap labels to an arbitrary layout without having to rebind every single key (maybe as a solution to this issue)

⁴ for example, instead of placing the 2nd most frequent command ▲ (15.5%) on a non-home row i it uses the home row k

⁵ this breaks the 'sticky' select_mode pending implementation of this feature request

⁶ (alphanumeric) characters produced as if you typed with a key are used to match cheat sheet labels, so this might not always match correctly the physical key layout. Press ⎋ or ␠ to hide. Tooltips show an ugly [object Object] instead for sub-modes instead of a description since that information is not part of the config, so requires more work to add