Every keybinding in Vim Motions is user-remappable. The mechanism depends on the context — editor keybindings use vim.keymap.set / nmap, oil explorer uses autocmds, the picker uses a dedicated keymap API, and global workspace navigation uses vim.obsidian.keymap.set / gmap.

Editor keybindings

All editor motions, actions, and operators have ex command aliases. Remap by mapping your preferred key to the ex command.

vim.keymap.set('n', 'gh', ':nextheading<CR>', { desc = 'Next heading' })
vim.keymap.set('n', 'gH', ':prevheading<CR>', { desc = 'Previous heading' })
vim.keymap.set('n', '<leader>s', ':splitvertical<CR>', { desc = 'Split vertical' })

Vimrc

nmap gh :nextheading<CR>
nmap gH :prevheading<CR>
nmap <leader>s :splitvertical<CR>

Removing a default binding

To move a binding to a different key and disable the original:

vim.keymap.del('n', ']h')
vim.keymap.set('n', 'gh', ':nextheading<CR>')

See ex-commands > Navigation and action commands for the full list of ex command aliases.

Remapping <Esc>

<Esc> is remappable in insert and visual mode, and a mapping you set wins over
the built-in mode exit:

vim.keymap.set('i', '<Esc>', '<Esc>:noh<CR>', { desc = 'Leave insert and clear search' })
vim.keymap.set('x', '<Esc>', 'll', { desc = 'Leave visual two columns right' })

Three details match Vim and are worth knowing before you bind it:

  • Only an exact <Esc> mapping wins. A longer one such as <Esc>q leaves
    bare <Esc> exiting the mode as usual, so binding a prefix cannot lock you
    into insert mode.
  • <C-[> follows your <Esc> mapping; <C-c> does not. <C-[> is Escape —
    the same byte — while <C-c> is a separate key. That makes <C-c> a reliable
    way out of insert mode whatever you bind to <Esc>.
  • A recursive mapping falls back to the built-in exit. vim.keymap.set('i', '<Esc>', '<Esc>', { remap = true }) leaves insert mode rather than looping.

Oil explorer keybindings

Oil keybindings are context-scoped — they only apply inside oil buffers. Use the OilEnter autocmd to set buffer-local keymaps.

vim.api.nvim_create_autocmd('OilEnter', {
    callback = function()
        vim.keymap.set('n', 'l', function()
            vim.obsidian.oil.open_entry()
        end, { buffer = 0 })
        vim.keymap.set('n', 'h', function()
            vim.obsidian.oil.parent()
        end, { buffer = 0 })
    end
})

Vimrc

nmap <C-h> :oilparent<CR>

Vimrc oil mappings are global

Vimrc nmap cannot scope to oil buffers only. Mappings apply everywhere. Use Lua with { buffer = 0 } for oil-only bindings.

Oil Lua functions

FunctionDescription
vim.obsidian.oil.open(path)Open oil for a directory
vim.obsidian.oil.close()Close oil buffer
vim.obsidian.oil.parent()Navigate to parent directory
vim.obsidian.oil.root()Navigate to vault root
vim.obsidian.oil.refresh()Refresh current listing
vim.obsidian.oil.toggle_hidden()Toggle dotfile visibility
vim.obsidian.oil.cycle_sort()Cycle sort order
vim.obsidian.oil.yank_path()Copy file path to clipboard
vim.obsidian.oil.reveal()Reveal in Obsidian file explorer
vim.obsidian.oil.open_entry()Open file/directory under cursor

See oil-explorer > Remapping keybindings for the full ex command table.

Picker keybindings

The picker operates outside the vim keymap system. Configure its keybindings via Lua:

vim.obsidian.pick_keymap({
    move_down = { 'ArrowDown', 'C-n' },
    move_up = { 'ArrowUp', 'C-p' },
    confirm = { 'Enter' },
    split_h = { 'C-s' },
    split_v = { 'C-v' },
    open_tab = { 'C-t' },
    scroll_down = { 'C-d' },
    scroll_up = { 'C-u' },
    close = { 'Escape', 'C-q' },
})

Key format: ArrowDown, Enter, Escape for special keys. Modifier prefixes: C- (Ctrl/Cmd), A- (Alt), S- (Shift), M- (Meta/Cmd). Prefixes can be combined: C-A-j for Ctrl+Alt+j. Only specified fields are updated — omitted fields keep their defaults.

Example using Alt+j/k for navigation:

vim.obsidian.pick_keymap({
    move_down = { 'A-j', 'C-j' },
    move_up = { 'A-k', 'C-k' },
})

Vimrc not supported

Picker keybindings cannot be configured via vimrc. Use Lua.

Global workspace navigation keybindings

Global keybindings apply in non-editor views (graph, PDF, canvas, etc.). Configure via vim.obsidian.keymap.set (Lua) or gmap (vimrc).

Lua

vim.obsidian.keymap.set('H', ':files', { desc = 'Find files' })
vim.obsidian.keymap.del('L')

Vimrc

gmap H :files
gunmap L

Ex command line

:gmap H :files
:gunmap L
:gmaps          " list all global mappings

The rhs must start with : — either :command (ex command) or :obcommand command-id (Obsidian command).

The File Explorer’s h/j/k/l are ordinary global mappings, so they follow the same rules:

gmap h :obcommand app:go-back    " replace the explorer's parent/collapse
gunmap l                         " remove expand/enter entirely

Note that j and k are single entries that scroll in other views and move the tree in the File Explorer, so remapping one replaces both meanings.

See vimrc > Global key mappings for details.

Summary

ContextLua APIVimrcEx command
Editor motionsvim.keymap.setnmap key :excommand<CR>N/A
Oil explorerOilEnter autocmd + buffer-localnmap key :oilcmd<CR>:oilparent, etc.
Pickervim.obsidian.pick_keymap(table)Not supportedN/A
Global workspace navvim.obsidian.keymap.set/delgmap / gunmap:gmap / :gunmap