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 correction when switching from Reading mode back to the editor
• 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

Key	Action
j / k	Scroll down / up
d / u	Scroll half a page down / up
gg / G	Jump to the top / bottom
f	Show hints for links and top-level Markdown embeds
F (Shift+F)	Show heading-fold hints
y	Show code-block copy hints
Y (Shift+Y)	Show inline-code copy hints
/	Open Obsidian's in-note search
z	Toggle reading focus

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 back to the editor also adjusts the cursor to the reading position.

Page-scroll bindings

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

Action	Default
Half page down / up	Ctrl+D / Ctrl+U
Full page down / up	Unassigned

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.

Key after selection	Action
Enter	Open the target
Shift+J / Shift+K	Scroll the preview
j / k	Scroll the note
y	Copy the target
Esc	Close the preview or cancel hints

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:

Selected target	Copies
[[Note#Heading|alias]], ![[Note#Heading]]	Note#Heading, without the alias
[text](folder/Note.md)	folder/Note.md
[text](https://example.com)	https://example.com
Footnote [^1] or ^[...]	The footnote's Markdown text

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:

Direction	Reuse an adjacent pane when possible	Always create a new split
Right	v → Enter	V → Enter
Below	h → Enter	H → 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

Key	Copies
y	A visible code block. The label sits at the block's top-right.
Y	A visible inline code span. A slightly smaller label sits on the span's top-left corner, so short code stays readable.

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:

Setting	Default	Range
Surrounding text opacity	50%	10–100%
Context blocks on each side	2	0–5

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.

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:

Key	Action
j / k	Scroll down / up
h / l	Scroll left / right; on a board, choose the previous / next column
d / u	Scroll half a page down / up
gg / G	Jump to the top / bottom
f	Show hints for links, cards, and board cards
F (Shift+F)	Show hints for group headings, to fold or unfold a group
J / K (Shift+J / Shift+K)	Switch to the next / previous view
/	Open the Bases search

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
• 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.