Obsidian Vim Scrolling

An Obsidian plugin that adds vim-style scrolling in reading mode when Obsidian's vim key bindings are enabled.

Design Idea

Obsidian's built-in vim key bindings (powered by CodeMirror's vim mode) are active in source and live preview modes — but reading mode renders static HTML with no editor, so vim navigation keys (j, k, Ctrl+D, Ctrl+U, gg, G) do nothing there.

This plugin fills that gap: it intercepts those keystrokes in reading mode and scrolls the viewport directly, giving you consistent vim muscle memory regardless of which mode you are in.

It also handles a common friction point: after scrolling in reading mode, switching back to source mode may leave the cursor far from the visible content. The plugin corrects the cursor position so it matches what you were reading.

Key Mappings

Key	Action
j	Scroll down one line
k	Scroll up one line
Ctrl+D	Scroll down half a page
Ctrl+U	Scroll up half a page
gg	Scroll to the top of the document
G	Scroll to the bottom of the document

Keys are only active when:

1. The current view is in reading mode (preview)
2. Obsidian's vim mode is enabled (Settings → Editor → Vim key bindings)

Design Details

No Animation

Scrolling is instant — scrollTop is set directly with no CSS smooth-scroll or animation. This is intentional:

• Key-repeat events (holding j or k) scroll continuously without animation queuing lag.
• The behaviour matches source mode vim motions, which are also instantaneous.

Repeated Key Strokes

Holding a key (e.g., j) produces repeated keydown events. Each event is handled independently — no debouncing or rate-limiting is applied — so the viewport scrolls smoothly as long as the key is held.

gg Detection

The gg command is triggered by pressing g twice within 500 ms. After the first g, the timer starts. If a second g arrives within the window, the view scrolls to the top.

Cursor Adjustment (Reading → Source Mode)

When you switch from reading mode to source mode, the CodeMirror editor restores the cursor to its last known position, which may no longer be visible (because you scrolled in reading mode). The plugin corrects this after the editor initialises:

• Cursor is outside the visible viewport (above or below) → cursor is moved to the first editable line of the current viewport.
• Cursor is within the viewport → cursor is left unchanged.

This ensures the editor opens with the cursor near the content you were reading.

Usage

1. Enable vim key bindings in Obsidian: Settings → Editor → Vim key bindings
2. Install and enable this plugin.
3. Open any note and switch to Reading mode (the book icon in the top-right, or via the command palette).
4. Use j/k, Ctrl+D/Ctrl+U, gg, and G to navigate.

Installation

Manual

1. Download main.js and manifest.json from the latest release.
2. Copy them to <Vault>/.obsidian/plugins/vim-scrolling/.
3. Reload Obsidian and enable the plugin under Settings → Community plugins.

Development

git clone https://github.com/xlongfeng/obsidian-vim-scrolling vim-scrolling
cd vim-scrolling
npm install
npm run dev   # watch mode — compiles src/main.ts → main.js