Vim Reading Navigation

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
• Vimium-style f hints for visible links
• 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

Key mappings

Built-in bare mappings

Configurable page-scroll bindings

Configure these Reading-mode bindings under Settings → Vim Reading Navigation, not Obsidian Hotkeys. Editor bindings are unaffected.

The settings page groups controls into Scrolling, Reading focus, and Links and previews. Existing saved preferences are retained when defaults change.

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

Built-in bare mappings and configurable page-scroll bindings are active only while the current Markdown view is in Reading mode, and they are ignored in inputs, editors, and modals. Lowercase j/k continue to scroll the note while an internal-link preview is open.

Press / in Reading mode to open Obsidian's native in-document search. Search remains live while typing; use Enter and Shift+Enter for the next and previous result. n and N are intentionally not remapped while the native search field has focus.

Link previews

Press f, then type the label beside a link to preview it. Notes, headings, blocks, and footnotes are supported. External links show their destination URL without fetching the page.

Split opening (optional)

Enable split opening under Settings → Vim Reading Navigation is on by default. Select a Markdown link, then:

Lowercase reuses an adjacent pane whose shared edge matches the source, adding a new tab; otherwise it creates a split. The destination opens in Reading mode, including heading/block links. Confirm within 3 seconds; after that, Enter opens in the current tab.

• Show preview opening guidance: on by default; disabled and hidden while split opening is off.
• Open external links immediately: off by default; enable to skip URL confirmation.

Non-Markdown files open normally but have no preview or split shortcut. Links inside embedded notes, tags, and obsidian:// links are excluded. Preview content is display-only.

Reading focus

Keep the passage you are reading bright while dimming surrounding text, without hiding the workspace or changing your pane layout.

Toggle and status

• Press z in Reading mode, click the focus icon in the pane header, or run Vim Reading Navigation: Toggle reading focus from the command palette.
• The header icon is highlighted while enabled, and a brief Obsidian notice confirms each toggle. The icon supports keyboard activation with Enter or Space.
• If your theme or settings hide the pane header, use z or the command; toggle notices still appear.
• Holding z does not toggle repeatedly. Inputs, modals, editors, and active link-hint input are left alone. Additional command shortcuts can be assigned under Settings → Hotkeys.

Focus follows the active Reading pane. Switching panes removes the effect from the previous pane and applies it to the newly active Reading pane. The enabled state is shared within the vault session, not stored independently for each pane. Other panes, link-hint overlays, and separate preview popups retain their appearance. Editing and non-Markdown views have no focus effect; returning to a Reading pane resumes it while enabled.

Focus range

The block nearest the viewport center and its surrounding context stay bright. Near the start or end of a note, the focus anchor moves toward that edge so the first and last blocks remain reachable. Notes that fit without scrolling stay fully bright. Scroll, resize, image loading, and rerendering update the focused passage automatically.

Configure Settings → Vim Reading Navigation → Reading focus:

The default highlights up to 5 blocks: the selected block plus 2 on each side. Set the context to 0 for only the selected block, or 5 for up to 11 blocks. At 100% opacity, surrounding text is not visibly dimmed, but focus remains enabled.

Both options are saved and applied immediately. Focus starts off after each plugin load; its enabled state is not saved. Existing saved preferences are retained when defaults change.

Block boundaries and limitations

Paragraphs, headings, lists, tables, code blocks, blockquotes, and similar top-level rendered blocks are supported. A long list, table, code block, or embed is treated as a single block, so a large block can keep most of the viewport bright. Nested elements are not dimmed again.

Only mounted top-level el-* wrappers directly inside .markdown-preview-sizer are considered; unsupported renderer layouts are left unchanged, and offscreen content is not materialized. This is a reading-focus feature, not a Zen mode that hides workspace UI.

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.