Vim Motions

A polished, Neovim-native experience inside Obsidian. Vim Motions adds what's missing from Obsidian's built-in Vim mode: Markdown-aware text objects, structural navigation, hard-wrap formatting, workspace keyboard control, EasyMotion, and a built-in .obsidian.vimrc loader.

Features

Markdown text objects

Operate on Markdown structures with standard Vim operators (d, c, y, v).

All delimiter-based text objects work across multiple lines (configurable scan range, default: 20 lines in each direction). Delimiters inside fenced code blocks are excluded from the scan.

Structural navigation

Jump between document structures. Works with counts (e.g., 3]h jumps 3 headings) and operators (e.g., d]h deletes to the next heading).

Hard-wrap operators (gq / gw)

Reformat paragraphs with Markdown-aware line wrapping — something Obsidian's built-in Vim mode does not support.

gq moves the cursor to the start of the formatted range. gw keeps the cursor at its original position. Both use the same wrapping engine.

The default wrap width is 80 columns. You can change it at runtime via Obsidian's developer console: CodeMirrorAdapter.Vim.setOption('textwidth', 100). Note: set textwidth=N in .obsidian.vimrc is parsed but does not currently propagate to the gq/gw operators due to a known limitation.

Behavior:

• Splits lines exceeding the textwidth at word boundaries.
• Preserves Markdown structural prefixes on continuation lines:
  • Blockquotes (>) — wrapped lines keep the > prefix.
  • Bullet lists (- , * , + ) — wrapped lines are indented to align with the text.
  • Numbered lists (1. ) — same alignment behavior.
  • Nested structures (> - text) — both prefixes are preserved.
• Merges short lines with matching prefixes back into the preceding line when they fit within the textwidth, producing a proper paragraph-reflow effect.
• Blank lines act as paragraph separators — wrapping stops and resumes at each paragraph.

Table navigation

Navigate Markdown table cells without leaving Vim mode.

Wraps to the next/previous row when reaching the end/start of a row. Skips separator rows (|---|---|).

Note: On keyboard layouts where | requires AltGr or a modifier key (e.g. German, Dutch, Nordic), the ]\|/[\| bindings may not work. Use ]c/[c instead — they do the same thing and work on all keyboard layouts.

Workspace keyboard control

Navigate Obsidian without a mouse, following Neovim window management conventions.

Note: The <C-w> prefix may conflict with Obsidian's default "Close current tab" hotkey. To use <C-w> bindings, go to Settings → Hotkeys, search for "Close current tab", and remove or rebind the Ctrl+W hotkey. The close-tab functionality remains available via :q or :quit.

Surround (vim-surround)

Add, change, or delete surrounding delimiters — brackets, quotes, tags, and more.

Targets: ", ', `, (, ), [, ], {, }, <, >, t (tag), b→), B→}, r→], a→>

Opening brackets (, [, { add inner spaces. Closing brackets ), ], }, > don't. < in replacement position triggers tag prompting (use > for angle brackets). f/F in replacement position triggers function wrapping. Count-prefix repeats the delimiter character for quotes (2ysiw* → **word**, 2ysiw~ → ~~word~~, 2ysiw= → ==word==). All surround commands support dot-repeat (.). Requires bundled fork mode.

Ex commands

EasyMotion / Hop

Jump to any visible position with two keystrokes.

Find motions:

Word motions:

Line motions:

Search motions:

All easymotion motions work in visual mode — v + easymotion extends the character selection, V + easymotion extends the line selection. Operator-pending mode (d + easymotion, c + easymotion, y + easymotion) works natively via the fork's async motion support.

All easymotion actions can be remapped in .obsidian.vimrc. Bidirectional variants (easyMotionBdWord, easyMotionBdFind, etc.) and repeat (easyMotionRepeat) are also available as named actions.

Hint mode (Vimium-style navigation)

Navigate the entire Obsidian interface without a mouse. Press <leader><leader>h (or a configurable global hotkey) to label every clickable element on screen — buttons, tabs, sidebar items, settings controls, editor panes, links — then type the label to activate it.

• Works everywhere: editor, sidebar, tab bar, settings modal, modals, popout windows
• Smart labels: single-character labels when few targets, two-character (home-row first) when many
• Keyboard recovery: Backspace resets after a wrong first character, Escape cancels
• Pane navigation: select an editor pane label to focus it (uses setActiveLeaf for proper Obsidian focus)
• Modifier support: hold Ctrl/Cmd while selecting a link to open in a new pane
• Internal links: [[wikilinks]] and [markdown](links) are opened via Obsidian's link resolver, not raw click
• Scroll-aware: only visible elements are labeled — items scrolled out of view in containers are excluded
• Global hotkey: configure a key combination in Settings → Vim Motions → Hint mode global hotkey that works even when modals (settings, command palette) have focus
• Registered as Obsidian command: vim-motions:show-hint-labels — assign a hotkey in Settings → Hotkeys or trigger from the command palette

Quality of life

• Neovim defaults — Y yanks to end of line (y$) and Q replays last recorded macro (@@), matching Neovim's defaults instead of CM Vim's legacy behavior.
• Vim mode status bar — shows NORMAL / INSERT / VISUAL / REPLACE in the status bar. Customizable per-mode text (including emoji) via settings.
• Vim chord display — shows pending keystrokes (e.g. 2d, gq) in the status bar as you type a multi-key command.
• Powerline-style status bar — optional colored mode indicator with per-mode background colors and a triangular separator. No special fonts required. Override colors via CSS custom properties (--vim-pl-normal-bg, etc.).
• Which-key hints — shows available key continuations in a popup after a short delay. Configurable: off, leader key only, or all partial keys. In "all" mode, pressing d shows available motions/text objects, g shows g-prefixed commands, etc.
• Ex command completion — Tab-complete ex commands as you type in the : command line.
• Macro recording indicator — shows RECORDING @{register} in the status bar when recording a macro.
• Scrolloff — configurable number of lines to keep visible above/below the cursor. Adapts to your font size automatically.
• Configurable insert escape — set jk, jj, or any two-key sequence to exit insert mode via set insertmodeescape=jk in your vimrc.
• Settings hot-reload — toggle features on and off without restarting Obsidian.
• Built-in .obsidian.vimrc — load key mappings and settings without needing obsidian-vimrc-support.

Vimrc support

Vim Motions has built-in support for .obsidian.vimrc files, compatible with obsidian-vimrc-support syntax. Place a .obsidian.vimrc file in your vault root:

" Example .obsidian.vimrc
let mapleader = " "

" Key mappings
nnoremap j gj
nnoremap k gk
nmap Y y$

" Leader key mappings
exmap saveFile obcommand editor:save-file
nmap <leader>w :saveFile

" Execute Obsidian commands
nmap <C-s> :saveFile

" Settings
set clipboard=unnamed
set tabstop=4
set textwidth=80
set shiftwidth=2
set expandtab
set insertmodeescape=jk

Supported commands: map, nmap, imap, vmap, noremap, nnoremap, inoremap, vnoremap, unmap, nunmap, iunmap, vunmap, set, let mapleader, exmap, obcommand, source.

Supported set options: clipboard (unnamed/unnamedplus — syncs yank/delete/paste with system clipboard), tabstop/ts, textwidth/tw, shiftwidth/sw, expandtab/et, insertmodeescape/ime. Use set noexpandtab to disable boolean options.

If obsidian-vimrc-support is also installed, Vim Motions skips its own :ob command registration to avoid conflicts.

Settings

All features can be toggled independently in Settings → Vim Motions. Changes take effect immediately without restarting.

• Text objects (on/off)
• Structural navigation (on/off)
• Hard-wrap operators gq/gw (on/off)
• Table navigation (on/off)
• Workspace navigation (on/off)
• Load .obsidian.vimrc (on/off)
• Vim mode status bar (on/off)
• Vim chord display (on/off, default: on)
• Powerline-style status bar (on/off, default: off)
• Vim mode display prompt — customizable text per mode (normal, insert, visual, replace)
• EasyMotion (on/off)
• EasyMotion dimming (on/off, default: on)
• Hint mode (on/off)
• Hint mode label characters (customizable)
• Hint mode global hotkey (press-to-record, works in modals)
• Scrolloff lines (0–20, default: 5)
• Multi-line text object scan range (5–200, default: 20)
• EasyMotion label characters (customizable)
• Which-key hints (off / leader key only / all partial keys, default: off)
• Leader key bindings (add/remove key-to-command mappings without editing vimrc)

Installation

From community directory

Search for "Vim Motions" in Settings → Community plugins → Browse.

Manual installation

1. Download main.js, manifest.json, and styles.css from the latest release.
2. Create a folder vim-motions in <your-vault>/.obsidian/plugins/.
3. Copy the downloaded files into that folder.
4. Restart Obsidian and enable the plugin in Settings → Community plugins.

Requirements

• Obsidian v1.1.1 or later
• Desktop only (mobile support planned for a future release)

Recommended setup

Disable Obsidian's built-in Vim mode (Settings → Editor → Vim key bindings → off). When built-in vim is off, Vim Motions provides its own enhanced vim engine (a fork of codemirror-vim) with:

• Neovim-correct behavior for dd cursor positioning, J join whitespace, di{ multiline brackets, dj/dk at document boundaries, :s cursor, % string-awareness, db/d2w cross-line whitespace, and more
• Async motion support enabling native operator-pending easymotion (d + easymotion, c + easymotion, y + easymotion)
• Theme-aligned cursor styling using Obsidian's CSS variables (--interactive-accent)

The plugin also works with built-in vim mode enabled — it extends whatever vim engine is active. But the fork provides a more accurate Vim experience.

Development

# Install dependencies
npm install

# Development build (watch mode)
npm run dev

# Production build
npm run build

# Lint
npm run lint

# E2E tests (requires nix develop on NixOS, or system libraries for Electron)
npm run test:e2e

# Coverage report (command-level test status)
npm run test:coverage

Testing strategy

The plugin uses a Neovim-backed golden comparison system inspired by Zed editor's Vim test architecture. Every Tier 1 Vim command (motions, operators, text objects, insert mode, visual mode) is tested against a real headless Neovim instance to verify behavioral parity.

How it works:

1. A headless Neovim is spawned via nvim --embed --headless and connected over msgpack-RPC.
2. The same keystrokes are sent to both Obsidian (via WebDriverIO) and Neovim.
3. The resulting editor state (content, cursor position, mode) is compared.
4. Expected Neovim output is pre-recorded as golden JSON files — CI compares against these without needing Neovim installed.

Test types:

• [nvim] tests — Neovim-compared via golden files. No hand-written expected values; Neovim's output is the spec.
• [obsidian] tests — viewport-dependent behavior (H/M/L, scroll, folds) that headless Neovim cannot verify.
• Tier 2 tests — plugin-specific features (Markdown text objects, structural navigation, workspace commands) with hand-written assertions.

Available commands:

# Run Neovim smoke test (verify client works)
npm run test:neovim-smoke

# Record golden files from Neovim (requires nvim binary)
npm run test:neovim-record

# Run tests with live Neovim comparison (requires nvim binary)
npm run test:neovim-compare

Intentional behavioral deviations from Neovim are documented in test/neovim/deviations.ts and KNOWN_LIMITATIONS.md. The deviation registry serves as the roadmap toward full Neovim parity — when it's empty (minus intentional overrides like Y→y$), the goal is achieved.

License

MIT — Emile Bangma