Vim Motions

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.

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.

Configure the wrap width with set textwidth=N in your .obsidian.vimrc (default: 80).

Behaviour:

• 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 behaviour.
  • 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 (|---|---|).

Workspace keyboard control

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

Ex commands

EasyMotion / Hop

Jump to any visible position with two keystrokes.

Quality of life

• Vim mode status bar — shows NORMAL / INSERT / VISUAL / REPLACE in the status bar.
• Which-key hints — when you press the leader key and pause, a floating overlay shows all available leader bindings.
• 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.
• 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, set, let mapleader, exmap, obcommand, source.

Supported set options: 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)
• EasyMotion (on/off)
• Scrolloff lines (0–20, default: 5)
• EasyMotion label characters (customizable)
• 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.13.0 or later
• Vim mode must be enabled (Settings → Editor → Vim key bindings)
• Desktop only (mobile support planned for a future release)

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

License

MIT — Emile Bangma