Vim Scrolling

An Obsidian plugin that brings vim-style navigation and search to Reading view when Obsidian's vim key bindings are enabled:

• Navigation: j/k, Ctrl+d/Ctrl+u, gg and G.
• Search: / and ? search the current note (incremental, smartcase, all matches highlighted); n/N jump between matches.
• Cursor sync: switching back to source mode moves the cursor into the part of the note 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
/	Search forward; opens a command line at the bottom
?	Search backward
n	Next match (in the search direction)
N	Previous match (opposite direction)
Esc	Clear search highlights

Keys are only active when:

1. The current view is in reading view (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.

Search

Pressing / (or ?) opens a command line at the bottom of the reading view.

• Incremental: matches are highlighted and scrolled into view as you type.
• Smartcase: case-insensitive unless the query contains an uppercase letter.
• Literal text: the query is not a regular expression; phrases spanning inline formatting (e.g. foo **bar**) still match.
• Highlighting: all matches are highlighted and the current one is emphasised (CSS Custom Highlight API, no DOM changes).
• Wrap around at the first/last match; the bar shows the match count.
• Enter confirms, Esc (or Backspace on an empty input) cancels. After confirming, use n/N and Esc to clear highlights.
• Shows "Pattern not found" when nothing matches.
• Only rendered content is searched.

Cursor Adjustment (Reading → Source Mode)

When you switch from reading view 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 view). 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 view (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

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 view 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 view 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 view, 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.