`which-key` integration

[ficcdaf]

Does this feature exist in Emacs orgmode core?

N/A

Orgmode link

No response

Feature value

Many Neovim users use which-key for help with remembering keybindings. A plugin like orgmode, with its dozens of mappings, benefits from this a lot.

When I first started using this plugin, was very overwhelmed by the number of keymaps. I thought that I could rely on which-key, but after pressing the org-prefix combination (<leader>o in my config), I was greeted by a large number of +X keymaps labels, which did not help me find my way. I feel that integrating which-key groups would go a very long way towards making the plugin more accessible for new users, which is something (I think) orgmode can improve on.

Orgmode already works well with which-key. However, there is missing support for one of its greatest features, groups. Groups allow us to create a label to describe keymaps that have a common prefix, helping users easily remember which key they need to press next to get to the category they want.

Additional context

For your reference, this is how which-key looks with orgmode on my setup. Kindly note that the +fzf org group is one that I added in my own config; I'm proposing to add a similar label for all of the "nested" keymaps.

I'm unclear whether this belongs in the main repo. It's not an emacs core feature, but it's also not an orgmode plugin, either; rather, an optional integration with a Neovim plugin. Let me know if this would be better suited as a separate plugin.

[kristijanhusak]

I use which-key, but only with default settings. I know that desc on the mapping shows in which key, but I don't know anything about the groups. How is group added?

[ficcdaf]

As far as I can tell, groups are a which-key specific feature. You can add them like this:

local wk = require("which-key")
wk.add({
  {
    "<leader>of",
    group = "fzf org",
  },
})

If a user has which-key installed, it's all but guaranteed to be loaded before other plugins. So in terms of an integration, I could see using pcall to check if the user has which-key loaded and, if so, call its add API to add the appropriate groups.

[ficcdaf]

@kristijanhusak does the API expose some way to get the LHS for each action? If so, I imagine the which-key integration could be done as an external plugin.