zulerne42 downloadsVim keys beyond the editor: Space leader menu with key hints, Reading view navigation and link hints, Harpoon-style file marks, .vimrc mappings, Latin layout outside Insert. Any keyboard layout.
Vim keys beyond the editor. Obsidian's Vim mode only works while you edit a note; Vim Layer adds the rest:
Space and pick a command from a menu of keys (Space f find a file, Space / search…), like which-key in Neovim.d/u to scroll half a page and j/k line by line, f to put letter labels on links and click them from the keyboard, J/K to switch tabs, i to start editing and Esc to go back to reading.s + two characters puts labels on the matches and S puts a label on every word; type a label to move the cursor there, like flash.nvim and hop.Space 1…Space 4, like Harpoon in Neovim.g, z, [ or ] in the editor, or g in Reading view, a bar lists the keys that can follow, your own mappings included.Everything works in any keyboard layout: keys are matched by their position on a QWERTY keyboard, so j also scrolls when a Cyrillic or Greek layout is on. In Vim Normal and Visual mode every key works by its position: Vim Layer learns your layout as you type and sets Vim's langmap from it, so letters and punctuation keys (ж is ;, б is ,) do what they do on QWERTY. Punctuation that types another Latin character is sent by position too: on a Russian layout the / key (which types .) opens search, Shift+4 is $ and Shift+3 (№) is #. The character after f, t, r and similar stays as typed, so fа finds a Cyrillic «а». Insert mode types as usual. Latin layouts are left as they are, including their letters outside ASCII (ö, ñ), so vimrc mappings for those keys keep working. A langmap set in your vimrc takes precedence.
Desktop only.
Install. Settings → Community plugins → Browse, search for Vim Layer, install and enable it (or open the listing). To install manually, download main.js, manifest.json and styles.css from the latest release into <vault>/.obsidian/plugins/vim-layer/.
Try Reading view. Open a note in Reading view (the book icon at the top of the note) and press j, d, f, Space. These keys work without any setup.
Turn on Vim mode for the editor: Settings → Vim Layer → Turn on Vim mode (or Obsidian's own Settings → Editor → Vim key bindings).
Create the vimrc. Settings → Vim Layer → Create vimrc writes .obsidian.vimrc to the vault root with these lines. They take effect at once, or when you next open a note in the editor:
" Space opens the Vim Layer leader menu, as in Reading view.
unmap <Space>
exmap leader obcommand vim-layer:leader
nmap <Space> :leader<CR>
" Jumps: s, then 2 characters of the target, then its label. S puts a label on every word.
exmap flash obcommand vim-layer:jump-to-chars
nmap s :flash<CR>
exmap hop obcommand vim-layer:jump-to-word
nmap S :hop<CR>
" Remove the quote below to make y and p use the system clipboard (also d, c and x).
" set clipboard=unnamed
If you already have a .obsidian.vimrc (from Vimrc Support), the button leaves it alone; add the lines you want and run Vim Layer: Reload vimrc. Obsidian does not show files starting with a dot, so edit it with any text editor.
Use it. In the editor, Space opens the leader menu and s / S jump. Space a marks the current file, Space 1…Space 4 jump to marked files, Space H lists them.
Optional next steps:
i edits, Esc returns).Space opens a bar at the bottom of the window. Type the next key to run a command or open a group; after a short pause (Hint delay) the bar lists the keys you can press. Backspace steps back, Esc closes.
In Reading view Space is bound by default. In the editor it needs the vimrc from the Quick start (Settings → Vim Layer → Create vimrc); without Vim mode, assign a hotkey to Vim Layer: Open leader menu in Settings → Hotkeys (Obsidian hotkeys cannot use a bare Space).
| Keys | Command |
|---|---|
Space f |
Quick switcher |
Space p |
Command palette |
Space / |
Search in vault |
Space e |
Toggle left sidebar |
Space w / Space q |
Save / close tab |
Space t n / t v / t s / t u |
New tab / split right / split down / reopen closed tab |
Space b |
Bookmarks |
Space o |
Outline |
Space a / Space H |
Mark the current file / list marked files |
Space 1…Space 4 |
Go to marked file 1…4 |
Meta/leader.yml.description: Leader
items:
f: switcher:open Find file # command ID, then a label
w:
command: editor:save-file # without a label the command's name is shown
n:
file: Inbox/Notes # open a note
a: vim-layer:harpoon-add Mark file
"1": vim-layer:harpoon-1 Mark 1
s:
description: Search # a group: Space s, then a key below
items:
c: command-palette:open Commands
g: global-search:open Grep
Enter; the ID (for example omnisearch:show-modal) is copied to the clipboard. Commands from other plugins work too.b, G, /, ?), a named key (space, enter, tab, backspace, up, f1…) or modifiers c (Ctrl), a (Alt), m (Cmd/Win), s (Shift) before a dash: c-enter, sa-tab. Capital letters are written as they are: G, not s-g. Quote keys that YAML treats specially: "1", "/".Vimium-style keys for reading notes. Reading view is Obsidian's mode for reading a note without editing it (the book icon at the top of a note, or Settings → Editor → Default view for new tabs). The keys work while a note is in Reading view, a base (.base file) is open or a tab is empty, and no text field has focus. In a base, j/k scroll and f labels the links to notes; the arrow keys, Enter and Esc keep working in the table as usual. The defaults are those of Vimium+ and mostly those of Vimium; J is the next tab and K the previous one, the other way round from Vimium (gt / gT work as in Vimium), and o opens the quick switcher.
| Keys | Action |
|---|---|
j / k |
Scroll down / up |
d / u |
Half a page down / up |
gg / G |
Top / bottom |
f |
Letter labels on links, buttons and collapsible callouts; type a label to click it |
F, or Shift on the last letter |
Same, opening links in a new tab |
/ |
Search in the note: type, Enter to stay on the first match, then n / N for the next / previous one; Esc closes |
J / K, gt / gT |
Next / previous tab |
t / x / X |
New tab / close tab / reopen closed tab |
H / L |
Back / forward |
b / B |
Open a bookmark here / in a new tab |
O |
Bookmark, recent file or URL in a new tab |
o / p |
Quick switcher / command palette |
Space |
Leader menu |
i |
Edit the note, cursor at the middle of the screen |
In the editor, Esc in Vim Normal mode returns to Reading view (from Insert mode, press Esc twice).
After the first key of a sequence (g of gg or g/), Vim Layer waits for the next key like Vim does, and after the hint delay a bar lists what can follow, with command names. Esc cancels.
Settings → Vim Layer → Key bindings holds every binding, one per line: the keys, then a command ID. Keys are written like in the leader keymap and separated by spaces (g g). A later line wins; - instead of a command removes a key. ↺ restores the defaults.
y yazi-fm:reveal # add: y runs a command from another plugin
g / omnisearch:show-modal # add a two-key sequence
x - # remove x
Vim Layer's own actions can go anywhere a command ID goes (hotkeys, the leader menu): vim-layer:scroll-down, scroll-up, scroll-half-page-down, scroll-half-page-up, scroll-to-top, scroll-to-bottom, hints, hints-new-tab, edit, read, bookmarks, bookmarks-new-tab, omnibar, search-next, search-previous.
| Setting | Default | What it does |
|---|---|---|
| Vim keys in Reading view | on | Turns all of the above on or off, in bases too |
| Open notes in Reading view | off | Notes open in Reading view; Obsidian's default view mode is restored when turned off |
| Esc returns to Reading view | on | Esc in Vim Normal mode leaves the editor |
| Turn on Vim mode | off | Turns on Obsidian's Vim key bindings while Vim Layer runs |
| Mode indicator | on | READING / NORMAL / INSERT / VISUAL in the status bar |
| Scroll step | 70 | Pixels per j/k |
| Hint characters | sadfjklewcmpgh |
Letters for labels, most convenient first |
| Hint targets | links, buttons, tabs, file tree… | CSS selectors of elements that get a label |
Two commands for the editor, mapped to s and S by the vimrc from the Quick start:
| Command | ID | What happens |
|---|---|---|
| Jump to characters | vim-layer:jump-to-chars |
Type 2 characters of the target (the text dims while you type); every match on screen gets a label. A single match is jumped to at once. |
| Jump to word | vim-layer:jump-to-word |
Every word on screen gets a label right away. |
Type the label to move the cursor; hold Shift on its last letter to select from the cursor instead. Labels closest to the cursor are the shortest. Esc, a click or scrolling cancels.
Any layout, no switching. Labels are shown in the letters of the current layout (Cyrillic labels on a Russian layout) and can be typed in any layout. In Jump to characters each key matches what it types in both layouts: on a Latin layout, the key with d/в finds both «d» and «в». The second layout is learned the first time you type in it, for example in Insert mode.
Settings (Settings → Vim Layer → Jumps): characters to type (1–3, default 2), case sensitivity, and the word pattern for Jump to word (default: 3 or more letters, digits or _ in any language).
A short numbered list of files (up to 9). Jumping back to a file puts you where you left it.
| Command | ID |
|---|---|
| Harpoon: add current file | vim-layer:harpoon-add |
| Harpoon: open list | vim-layer:harpoon-list |
| Harpoon: go to file 1…9 | vim-layer:harpoon-1 … vim-layer:harpoon-9 |
| Harpoon: remove current file | vim-layer:harpoon-remove |
The built-in leader menu has them: Space a adds, Space H lists, Space 1…Space 4 jump. With your own keymap file, add them there (a, H, "1"…"4", as in the example above) or to Settings → Hotkeys; files 5–9 have commands too.
In the list: j/k move, Enter or l opens, 1–9 open by number, J/K reorder, dd removes, p puts the removed file back, Esc closes. Renamed files stay in the list; deleted files drop out. A list from the Harpoon plugin (harpoon-cache.json) is imported once.
When you leave Insert mode, Vim Layer remembers your keyboard layout and switches to a Latin one, so Normal mode commands work; when you enter Insert mode, your layout comes back. Off by default; it needs a small command-line tool.
macOS
Install macism: brew install laishulu/homebrew/macism.
Settings → Vim Layer → Switch input method: on. These settings run shell commands, so they are kept on each device and are not synced with the vault. The default commands already use macism:
| Field | Value |
|---|---|
| Extra PATH | /opt/homebrew/bin (Apple silicon) or /usr/local/bin (Intel) |
| On leaving Insert | macism com.apple.keylayout.ABC |
| On entering Insert | macism {{im}} |
| Get current | macism |
If your Latin layout is not ABC, switch to it and run macism in Terminal to get its ID (for example com.apple.keylayout.US).
Windows: im-select: im-select.exe 1033 on leaving, im-select.exe {{im}} on entering, im-select.exe to get the current one; put its folder in Extra PATH.
Linux (fcitx5): the defaults use fcitx5-remote.
Vim Layer runs .obsidian.vimrc from the vault root (Settings → Vim Layer → Vimrc file) when the first editor opens. Create vimrc in the same section writes a starting file (see Quick start). After editing it, run Vim Layer: Reload vimrc.
| Line | Meaning |
|---|---|
nmap U <C-r> |
map, nmap, imap, vmap, noremap, unmap, nunmap, iunmap, vunmap as in Vim |
exmap back obcommand app:go-back |
Define an Ex command; obcommand runs an Obsidian command by ID |
nmap <C-o> :back<CR> |
Map keys to that Ex command |
let mapleader = "," |
Leader key for <leader> in mappings |
set clipboard=unnamed |
Yank to and paste from the system clipboard |
set tabstop=4 |
Tab width |
source other.vimrc |
Run another file |
Built in: ]]/[[ next/previous heading (any level), gl/gL next/previous link, gf or gx follow the link under the cursor (notes and web links).
After g, z, [ or ] in Normal or Visual mode, a bar at the bottom lists the keys that can follow: Vim's own commands, the motions above and your vimrc mappings, described by the Obsidian command they run (g/ → Omnisearch: Vault search). It appears after the leader menu's Hint delay, so it stays out of the way when you type fast. Turn it off with Settings → Vim Layer → Key hints (this also turns off the Reading view hints).
Vim Layer covers Spacekeys, Vimium+, Harpoon, Vim IM Control, Vimrc Support and the editor jumps of Jump to link, and reads the same files: the Spacekeys keymap, the Harpoon list and .obsidian.vimrc. For Jump to link, map s/S to vim-layer:jump-to-chars/vim-layer:jump-to-word instead of mrj-jump-to-link:activate-lightspeed-jump/activate-jump-to-anywhere. Turn the old plugin off when you switch. Until you do, the matching part of Vim Layer stays off (Vimium+, Vim IM Control, Vimrc Support), so keys are not handled twice. In a Spacekeys keymap, replace spacekeys:leader with vim-layer:leader and harpoon:… commands with the vim-layer:harpoon-… ones.
Not carried over: the Web viewer keys and shell commands of Vimium+; jscommand, jsfile, sendkeys and surround of Vimrc Support.
npm install
OBSIDIAN_VAULT=/path/to/vault npm run install-vault
Vim Layer follows the behavior and formats of these MIT-licensed plugins and adapts parts of their code (see THIRD-PARTY-NOTICES.md):
MIT