Vim mode in Obsidian: setup, vimrc and limits

• Open Settings, choose Editor, scroll to Advanced, and switch on Vim key bindings.
• Press i to type and Esc to return to Normal mode, as in Vim.

There is nothing else to install for the basics. Mappings that last, the system clipboard and the extras below come from a plugin.

Obsidian's Vim mode is, in the words of the Vimrc Support plugin's author, mostly the codemirror-vim extension for CodeMirror. That project lists, among its features:

• All the common motions and operators, including text objects (ciw, da(, ci", dap).
• Visual mode in all three flavours: character (v), line (V) and block (Ctrl-v).
• Full macro support with q and @.
• Marks with ` and ', and the jump list with Ctrl-o and Ctrl-i.
• Incremental, highlighted search with /, ?, *, #, g* and g#, with history.
• :s and :%s, including the confirm flag, plus :sort, :global, and :map, :nmap and :vmap.

The same project says plainly that it "does not strive to become a complete vim implementation", so expect gaps in the less common corners. A good habit: try a command at the : prompt in Obsidian before relying on it.

Anything you :map by hand is gone when Obsidian restarts. The community plugin Vimrc Support (by esm7) fixes that by reading a file of Vim commands when a vault opens.

• Install it from Settings › Community plugins (turn community plugins on first), and keep Obsidian's Vim key bindings switched on: the plugin adds to them, it doesn't replace them.
• Create a file named .obsidian.vimrc in the vault root, not inside the .obsidian folder. Each vault needs its own copy.

A useful start, taken from the plugin's own example:

• nmap j gj and nmap k gk: move by screen line, which matters in notes full of wrapped paragraphs.
• nmap H ^ and nmap L $: start and end of line.
• nmap <F9> :nohl<CR>: clear search highlighting.
• set clipboard=unnamed: yank to the system clipboard.

For j k to leave Insert mode, try :imap jk <Esc> at the : prompt first; the plugin's author recommends testing every command interactively before adding it to the file, because commands that fail in the file fail silently.

Vimrc Support adds obcommand, which runs any Obsidian command by its ID. Type :obcommand with no arguments and the full list of IDs appears in the developer console (Ctrl+Shift+I).

Because of a CodeMirror bug, mapping straight to a command with an argument doesn't work, so name it first with exmap, then map the name:

• exmap back obcommand app:go-back
• nmap <C-o> :back<CR>
• exmap forward obcommand app:go-forward
• nmap <C-i> :forward<CR>

Note the colon: exmap names have none, the nmap needs one. You may also need to remove Obsidian's own hotkey for a key before your mapping wins.

The plugin has a few more extras: surround to wrap a word or selection in text of your choice (handy for making a wikilink), pasteinto to paste the clipboard into the selected text or word (useful for making links), and ready-made motions: [[ and ]] for the previous and next heading, gl and gL for links, gf to open the link under the cursor, and zk and zj to move while skipping folds.

• No real Vim underneath. Plugins, Vim script and most options from a real .vimrc don't apply; the file only understands what CodeMirror's Vim mode and the plugin support.
• Ex mappings need `<CR>`. Since Obsidian 1.7.2, a Normal mode mapping to an Ex command must end in <CR>, as in real Vim: nmap <F9> :nohl<CR>, not nmap <F9> :nohl.
• Silent failures. A line in .obsidian.vimrc that doesn't work produces no error.
• `obcommand` isn't an official API, so a future Obsidian update could break mappings built on it.
• JavaScript commands (jscommand, jsfile) are off by default, and the plugin warns about the security risk of turning them on.
• Maintenance. The plugin's author is looking for a new maintainer and only handles urgent fixes, so check its page before depending on it heavily.

The motions are the same as in Vim, and the course teaches them in a real editor in the browser.