Vim Reading Navigation

Navigate, search, scroll, preview, open links, and focus on what you read in Obsidian's Reading mode without leaving the keyboard.

[!NOTE] Obsidian's Vim key bindings setting is not required.

A fork of xlongfeng/obsidian-vim-scrolling that adds plain d/u half-page scrolling, / native search, an f link hint mode, persistent link previews, and pop-out window support. Published with the original author's approval — see Credits.

Features

• Vim-style instant scrolling in Reading mode, including key repeat
• Link previews with Vimium-style f hints for visible links
• Heading folds with Vimium-style F hints for visible heading sections
• Code copy with Vimium-style y hints for code blocks and Y hints for inline code
• Persistent, mouse-independent Markdown previews for internal links and standard or inline footnotes
• Local external-link destination confirmation before opening in the system browser
• Cursor placement starting 45% down the viewport when switching from Reading mode to the editor, without requesting a scroll
• Native in-document search from Reading mode with /
• Main-window and pop-out-window support
• Reading focus with z or a native pane-header toggle, adjustable opacity, and configurable context blocks
• Bases keyboard navigation (experimental): scrolling, f hints that click links and cards, group folds, view switching, and / search

Key mappings

While hints are showing:

• Type the lowercase label to choose a target. Labels never use f or y.
• Press Esc, or any other key that is not a label, to close the hints. Hint keys (f, F, y, Y) and keys such as G or / only close the hints, so press the key again to use it.
• Ctrl, Cmd, and Alt shortcuts close the hints and still run, for example Ctrl+U or Obsidian's own shortcuts.

Mappings apply only in Reading mode and, when enabled, Bases files, and leave inputs, editors, and modals alone. Switching from Reading mode to the editor also triggers cursor placement without requesting a scroll; see Switching between reading and editing.

Page-scroll bindings

Configure these in Settings → Vim Reading Navigation, not Obsidian Hotkeys.

Editor bindings are unaffected. On Windows and Linux, assigning Ctrl+F overrides in-note search in Reading mode.

In search, use Enter / Shift+Enter for the next / previous result.

Link previews

Press f, then type a hint label to select a link or Markdown embed.

Selecting a target does not scroll the note unless the target is cut off at the edge of the pane. The preview opens below the target, or above it when it does not fit below.

Supported targets include notes, headings, blocks, footnotes, external web links, and top-level Markdown embeds. Embed hints appear beside the native open icon. Links inside embeds and non-Markdown embeds are excluded.

Standard footnotes jump to their definitions; inline footnotes are preview-only. Other non-Markdown file links open normally without a preview.

y copies what the selected target points to, as written in Markdown, and keeps the selection and preview open:

Press Esc first to show code-copy hints with y instead.

External links show a URL confirmation before opening. Enable Open external links immediately to skip confirmation.

Split opening

Select a Markdown link or embed, then press a direction key followed by Enter:

Reusing a pane adds a new tab rather than replacing its current note. Destinations open in Reading mode and preserve heading/block targets.

Confirm within 3 seconds; otherwise, Enter opens in the current tab. Split opening and its preview guidance are enabled by default and can be disabled in settings.

Heading folds

Press F, then type the label beside a visible heading to fold or unfold its section. The heading stays visible; its section includes nested headings up to the next heading of equal or higher level.

Code copy

Type the label to copy; the copied code is outlined briefly.

• Code blocks use Obsidian's own copy button, so the copy matches a mouse click: the code only, without the ``` fences or language name. Blocks without a native copy button, such as Mermaid diagrams, get no hint.
• Inline code copies the text inside the backticks. Code Styler titles and icons are left out.
• Blocks and spans inside callouts and embedded notes are included.

Reading focus

Press z, click the pane-header focus icon, or run Toggle reading focus from the command palette.

The passage near the viewport center stays bright while surrounding text dims. Focus follows the active Reading pane without hiding the workspace.

Configure Settings → Vim Reading Navigation → Reading focus:

Lists, tables, code blocks, and embeds are treated as whole blocks, so large blocks may keep much of the screen bright.

Preferences are saved, but focus starts off each time the plugin loads.

Switching between reading and editing

Obsidian controls the viewport when switching modes. This plugin does not record or restore scroll positions, and does not correct Obsidian's mode-switch positioning. It only places the cursor within the editor viewport after switching from Reading mode.

Cursor placement starts 45% down the editor viewport. This is fixed, with no setting:

• Every switch to editing finds a new cursor position, regardless of the previous cursor location.
• Starting at that height, the plugin searches downward for a fully visible text row and places the cursor at its start. It uses editor coordinates to skip rendered blocks and reject rows above the starting point; it does not parse block types.
• Cursor placement never requests a scroll. If no suitable row can be identified in the visible search area, no cursor move is made.

Each pane and pop-out is handled separately. Pending cursor placement is cancelled by user interaction or a changed view. Late-loading images and Live Preview formatting can still change the layout.

Bases

Experimental, off by default. Turn on Settings → Vim Reading Navigation → Experimental → Keyboard navigation in base files. Bases has no public API for its own views, so this relies on Obsidian internals and an Obsidian update may break it.

In a .base file:

Choosing a hint clicks the target exactly like the mouse: a link opens its note or web page, a card opens its note, and a group heading folds its group. There is no preview.

• Scrolling, hints, and the page-scroll bindings work in Obsidian's table, cards, list, and board layouts. Views from other plugins, such as Maps, keep their own keys; J / K and / still work there.
• A board scrolls each column on its own. The first column in view starts chosen, outlined in the accent color, and j / k, d / u, gg / G, and the page-scroll bindings scroll it. h / l move to the neighboring column and scroll the board to show it.
• Group headings appear in a table, cards, or list grouped by a property. Board columns do not fold.
• Keys the table uses itself, such as the arrow keys, Tab, and Enter, are left alone, and so is typing in a cell or the search box.

Usage

1. Open a Markdown note in Reading mode.
2. Use the built-in mappings above, configure page-scroll bindings in Settings → Vim Reading Navigation, or press f to select links.
3. Press z or click the focus icon in the pane header to enable reading focus. Adjust its opacity and context range under Settings → Vim Reading Navigation → Reading focus.

Installation

From the community store (recommended)

Install Vim Reading Navigation from Settings → Community plugins → Browse, or use the "Add to Obsidian" button on the store page.

From source

To build the latest development version yourself:

Prerequisites

• Node.js 18+ and npm

1. Build

git clone https://github.com/DS-argus/vim-reading-nav
cd vim-reading-nav
npm install
npm run build        # type-checks, then bundles src/ → main.js

This produces main.js at the repo root. The three files Obsidian needs are main.js, manifest.json, and styles.css.

2. Copy into your vault

Create the plugin folder if it doesn't exist, then copy the three artifacts in.

macOS / Linux:

cp main.js manifest.json styles.css "<Vault>/.obsidian/plugins/vim-reading-nav/"

Windows (PowerShell):

Copy-Item main.js,manifest.json,styles.css "<Vault>\.obsidian\plugins\vim-reading-nav\"

.obsidian is a hidden folder. The plugin folder name must match the plugin id (vim-reading-nav).

3. Enable

Reload Obsidian (Reload app without saving from the command palette), then enable Vim Reading Navigation under Settings → Community plugins.

Live development

npm run dev   # watch mode — recompiles main.js on save

Re-copy main.js into the vault and reload Obsidian after each change, or point esbuild's output (esbuild.config.mjs) directly at your vault's plugin folder to skip the copy step.

Credits

A fork of obsidian-vim-scrolling by xlongfeng. The original provides the reading-mode scrolling and cursor-adjustment behaviour; this fork adds:

• Plain d / u half-page scrolling
• Configurable Reading-mode page-scroll bindings
• Cursor placement starting 45% down the viewport when switching to editing, without requesting a scroll
• An f Vimium-style link hint mode with persistent previews and link activation
• Pop-out window support
• / shortcut for Obsidian's native in-document search
• Footnote previews
• External destination confirmation

Published to the community plugin directory with the original author's explicit approval, per Obsidian's fork policy.

Distributed under the same 0BSD license as the original.