Why is it "highly recommended" to set keymaps with "vim.normalModeKeyBindings" via settings.json instead of keybindings.json?

[brandonbeaumia]

The documentation states "It is highly recommended to remap keys using vim commands like "vim.normalModeKeyBindings"": can anyone explain why this is? Is it just to avoid the verbosity of keybindings.json? I am tempted to ignore this advice if that is the only reason, but want to make sure I'm not missing anything in the docs that explains why this matters.

[nicolaerario]

I have same question, more for curiosity.
One thing I can think can be, for example, this scenario:
You toggle vim mode with toggleVim command (like you can do in other editors); then, if you set keys with vim.normalModeKeyBindings, then vim mode can be properly "shut down". Instead, if you set them in the keybindings.json, you have to use them.

[johnfn]

This is because VSCodeVim doesn't have knowledge of what you've defined in keybindings.json, so it can't use those actions to perform more complicated actions. For instance, if you use keybindings.json to remap a to deleting a line, and then you do 5a, VSCodeVim won't know to delete 5 lines.

[mogelbrod]

Specifying chorded key bindings as VSCode bindings (via UI or keybindings.json) will AFAIK also prevent the chords from being picked up by VSCodeVim. If I for example bind ctrl+g b to anything in keybindings.json then VSCodeVim will no longer pick up any key maps that contain or start with ctrl+g.

[brandonbeaumia]

This all makes a lot of sense, thanks everyone! Guess the complexity and modes means that we want Vim to handle as much as possible.