VimNav Documentation

Complete guide to vim-style browser navigation with keyboard shortcuts, advanced features, and configuration options.

Getting Started Navigation Quick Nav Modes Commands Configuration Advanced

Quick Reference

Press ? anytime in VimNav to see the help overlay with all keybindings.

🚀 Getting Started

Installation

VimNav is available as a Chrome extension. Follow these steps to get started:

  1. Install VimNav from the Chrome Web Store
  2. Pin the extension to your toolbar for easy access
  3. Visit any webpage and start using vim keybindings immediately
Note: VimNav works on all websites and requires no additional setup or configuration.

First Steps

Once installed, VimNav is immediately active on all web pages. Try these basic commands:

? Show the help overlay with all keybindings
jk Scroll down and up on any page
e Open the tab navigator overlay
o Open the url search for quick navigation to new urls, history or search
f Enter hint mode to click links with keyboard

Basic Usage Patterns

VimNav follows vim's modal philosophy. You're always in one of several modes:

  • Normal Mode - Default mode for navigation and commands
  • Insert Mode - For typing in form fields (enters automatically)
  • Visual Mode - For text selection and manipulation
  • Hint Mode - For keyboard-only link clicking

🔄 Mode System

VimNav uses vim's modal system for different types of interaction.

Normal Mode

The default mode for navigation and commands. Most keybindings work in normal mode.

Esc Always returns you to normal mode from any other mode
EscEsc Focus main body for reliable vim navigation

Insert Mode

Automatically activated when you focus input fields, text areas, or contenteditable elements.

i Manually enter insert mode (finds nearest input)
Esc Exit insert mode and return to normal mode

Visual Mode

Select and manipulate text elements on the page. See the Visual Mode section for details.

Hint Mode

Click links and interactive elements using keyboard hints. See the Hint Mode section for details.

🌐 Quick Navigation

Instantly navigate to URLs, search engines, or browse history with the URL search overlay.

o Open URL search overlay for quick navigation

Navigation Features

The URL search overlay provides multiple navigation options:

  • Direct URLs - Type any URL to navigate directly (auto-adds https://)
  • Search Engines - Type search terms to search with your default search engine
  • History Search - Searches your browser history as you type
  • Bookmarks - Finds matching bookmarks in your browser
  • Smart Suggestions - Provides intelligent suggestions based on your input

Navigation Controls

jk
Navigate up/down through URL suggestions
Enter
Navigate to selected URL or search term
Ctrl+Enter
Open selected URL in new tab
Esc
Close URL search overlay
Pro Tips:
  • Use search terms without domain type strings to search with your default engine
  • History results show page titles and URLs for easy identification

📑 Tab Management

VimNav provides powerful tab navigation and management inspired by NERDTree.

Opening Tab Navigator

e Toggle tabs overlay - shows all open tabs in current window
Ctrl+P Telescope-style tab search (Chrome shortcut integration)

Tab Navigation

When the tabs overlay is open:

jk
Navigate tabs up/down
gg
Jump to first tab
G
Jump to last tab
Enter
Switch to selected tab
xd
Close selected tab
/
Focus tab search input

Tab Actions

r Reload selected tab
a Show tab group editor for organizing tabs
Esc Close tabs overlay and return to normal mode

🎯 Hint Mode

Click links, buttons, and interactive elements without using the mouse.

Using Hint Mode

f Enter hint mode - shows letter hints on clickable elements
a-z Type hint characters to narrow down selection
Enter Click the selected element
Backspace Delete last character or exit hint mode
Esc Exit hint mode without clicking

Hint Targets

Hint mode automatically detects and highlights:

  • Links (<a> elements)
  • Buttons (<button> elements)
  • Form inputs (input, select, textarea)
  • Clickable elements with click handlers
  • Elements with role="button" or tabindex
Tip: Hint characters are case-insensitive. Type partial hints to filter - you don't always need to complete the full hint sequence.

👁️ Visual Mode

Select and manipulate text content on web pages using vim-style text selection.

Entering Visual Mode

v Enter visual mode - shows hints on text elements
a-z Type hint to select a text element for manipulation
Enter Start text selection within the chosen element

Text Selection

Once you've selected an element and entered text selection mode:

hl
Extend selection left/right by character
jk
Extend selection down/up by line
wb
Extend selection by word forward/backward
gg
Extend selection to start of element
G
Extend selection to end of element

Text Actions

y Copy selected text to clipboard and exit visual mode
d Delete selected text and exit visual mode
Esc Exit visual mode without performing any action

📍 Marks System

Set bookmarks on pages and navigate between them quickly, similar to vim marks.

Creating Marks

m Enter mark creation mode
a-z Create local mark (remembers position on current page only)
A-Z Create global mark (remembers page URL and position across tabs)

Navigating to Marks

' Enter mark navigation mode
a-z Jump to local mark (scrolls to position on current page)
A-Z Jump to global mark (opens tab if needed and scrolls to position)

Mark Management

Use command mode for advanced mark management:

:marks Show all marks with their locations
:marks clear Clear all local marks for current page
:marks clearAll Clear all marks (local and global)

⚡ Command Mode

Execute vim-style commands for advanced functionality and extension features.

Opening Command Mode

: Open command input - type commands and press Enter to execute

Tab Commands

:tabs
Open tabs overlay (same as pressing 'e')

Marks Commands

:marks
Show all marks with their page URLs and positions
:marks clear
Clear all local marks for the current page
:marks clearAll
Clear all marks (both local and global)
:marks remove a
Remove a specific mark (replace 'a' with mark name)
:marks navigate A
Jump to specific mark (replace 'A' with mark name)

📚 History Search

Search and filter your browser history with powerful regex and date filtering.

Basic History

:history
Show browser history from the last 7 days

History with Regex Filtering

:history regex{vimnav.*}
Filter history entries matching regex pattern
:history regex{github.*issues}
Find GitHub issues in your history

History with Time Filters

:history back{24h}
Show history from last 24 hours (supports: s/m/h/d)
:history back{3d}
Show history from last 3 days
:history from{12-24-2025}
Show history from specific date forward

Combined Filters

:history regex{docs.*} back{7d}
Find documentation pages from the last week
:history from{8-1-2025,8-3-2025}
Show history between two specific dates
Pro Tip: History search is perfect for finding that article or documentation you visited but can't remember the exact URL. Use regex patterns to search by domain or keywords.

⚙️ Extension Configuration

VimNav provides two ways to configure the extension: through the Side Panel and the Extension Settings Page.

Side Panel Configuration

The side panel provides quick access to essential VimNav features and settings.

Opening the Side Panel

Chrome menu
Right-click the VimNav extension icon → "Open side panel"
Extension menu
Click the VimNav extension icon in the toolbar

Side Panel Features

The side panel includes:

Status Overview
View extension status and active tab count
Vim Mode Toggle
Enable/disable vim navigation globally
Mode Indicator Settings
Configure visual mode indicators and key help display
Performance Settings
Adjust element limits and shadow DOM support
URL Filtering
Configure site-specific blocking/allowing with blacklist/whitelist modes

Extension Options Page

VimNav provides a dedicated options page for additional settings not available in the side panel.

Opening the Options Page

Chrome extensions page
Go to chrome://extensions/ → Find VimNav → Click "Details" → Click "Extension options"
Right-click extension icon
Right-click VimNav icon → "Options"
Direct URL
Navigate to chrome-extension://[extension-id]/options.html

Options Page Settings

The options page contains settings focused on scrolling behavior and keyboard navigation:

Scrolling Settings
Scroll Behavior
Choose between smooth or instant scrolling animations
Small Scroll Distance
Configure pixel distance for j/k key scrolling (10-200px, default: 100px)
Page Scroll Ratio
Set fraction of viewport height for page up/down (0.1-1.0, default: 0.8)
Panel Settings
Sidepanel Position Info
Instructions for changing Chrome's side panel position (controlled by browser, not extension)
Keyboard Settings
Vim Keys Toggle
Enable/disable vim-style navigation keys (j/k for scroll, gg/G for top/bottom)

Available Settings in Side Panel

Status Overview

Extension Status
Shows current state (Ready/Active)
Active Tab Count
Displays total number of open tabs

Vim Mode Control

Controls Toggle
Enable/disable vim navigation across all tabs
Real-time Updates
Changes apply immediately to all active tabs

Mode Indicator Settings

Mode Indicator
Toggle display of current mode (NORMAL, VISUAL, etc.)
Key Help Display
Show/hide keybinding help menu
Instant Updates
Changes apply immediately without refresh

Performance Settings

Element Limits: Configure maximum elements to performance issues on large pages

Hint Mode Limit
Default 150 elements (range: 50-1000)
Visual Mode Limit
Default 100 elements (range: 50-500)
Scroll Target Limit
Default 50 elements (range: 25-200)
Tabs Overlay Limit
Default 200 tabs (range: 100-2000)
URL Search Limit
Default 500 items (range: 200-1000)
Shadow DOM Support
Enable/disable shadow DOM element detection
Reset to Defaults
Restore all performance settings to recommended values

URL Filtering System

The URL filtering system provides granular control over where VimNav is enabled.

Core Features

On/Off Toggle
Enable/disable URL-based site filtering
Dual Mode Operation
Switch between blacklist and whitelist approaches
Pattern Management
Add/remove URL patterns with wildcard support
Current Site Quick Add
One-click add current website to filter list
Real-time Updates
Changes apply immediately to all tabs
Privacy Protection
All filtering happens locally - no data sent to servers

Filtering Modes Explained

Blacklist Mode (Recommended for Most Users)
Default Behavior
VimNav works on ALL websites by default
Pattern Effect
Only BLOCKS VimNav on sites matching your patterns
Use Case
Perfect for blocking problematic sites (webmail, internal apps, etc.)
Empty List
VimNav works everywhere
Example
Block on *://mail.google.com/* but work everywhere else
Whitelist Mode (Restrictive/Enterprise)
Default Behavior
VimNav is BLOCKED on all websites by default
Pattern Effect
Only ALLOWS VimNav on sites matching your patterns
Use Case
Perfect for restricted environments or focused workflows
Empty List
VimNav blocked everywhere
Example
Only allow on *://github.com/* and *://stackoverflow.com/*

URL Pattern Format

*://example.com/* All protocols, entire domain and all paths
https://example.com/* HTTPS only, entire domain and all paths
*://subdomain.example.com/* All protocols, specific subdomain
*://example.com/app/* All protocols, specific path prefix
*://internal.company.com/admin* All protocols, specific admin paths

Pattern Matching Rules

* Matches any character sequence
Case Sensitivity Patterns are case-insensitive
*:// Protocol wildcards match both http:// and https://
/* Path wildcards: /* matches any path, /app* matches paths starting with /app
Query Parameters Query parameters are ignored in matching

Configuration Tips

For New Users

1. Default Settings
Start with default settings - they work well for most users
2. Mode Indicators
Enable Mode Indicators to see current vim mode while learning
3. Performance Settings
Adjust Performance Settings if experiencing slow performance on complex pages
4. URL Filtering
Use URL Filtering to disable VimNav on sites that conflict with vim keybindings

For Organizations/Power Users

1. URL Filtering Control
Use URL Filtering to control deployment across company websites
2. Performance Limits
Set Performance Limits based on typical hardware and usage patterns
3. Mode Indicators
Configure Mode Indicators for user training and support
4. Blacklist Mode
Use Blacklist Mode to block VimNav on internal web applications

Performance Optimization

Reduce Element Limits
On slower machines or complex websites
Disable Shadow DOM Support
If not needed (slight performance gain)
Use URL Filtering
For JavaScript-heavy applications that conflict
Monitor Active Tab Count
Performance may degrade with 100+ tabs

URL Filtering Best Practices

Blacklist Mode
Start with this for most users - only block problematic sites
Whitelist Mode
Use for restricted environments - only allow on approved sites
Pattern Examples:
  • *://internal.company.com/* - Block/allow entire internal domain
  • https://app.example.com/* - HTTPS only, specific application
  • *://mail.google.com/* - All protocols, specific service

Settings Persistence

All VimNav settings are automatically saved to Chrome's local storage.

Automatic Saving

Immediate Save
Settings save immediately when changed
No Manual Action
No manual save/export required
Browser Restart
Syncs across browser restarts
Updates
Preserved during extension updates

Settings Backup

Settings are stored locally in Chrome's extension storage and are not automatically synced across devices. For manual backup:

Chrome DevTools Access
Settings are accessible via Chrome DevTools → Application → Storage → Extension Storage
Advanced API Backup
Advanced users can backup via chrome.storage.local API
Future Import/Export
Future versions may include import/export functionality

Troubleshooting Settings

Settings not applying
Refresh active tabs after changes
Settings reset
Check if extension was reinstalled (clears local storage)
Performance issues
Reset performance settings to defaults and adjust gradually

⚙️ Settings & Configuration

Customize VimNav behavior and appearance to match your workflow.

Debug & UI Options

M Toggle UI indicators (mode display, keybinding hints)
Shift+D Toggle debug mode for development and troubleshooting
? Show help overlay with all keybindings

Extension Settings

Access VimNav settings through the Chrome extension management:

1. Right-click Extension Icon
Right-click the VimNav extension icon
2. Select Options
Select "Options" from the context menu
3. Configure Settings
Configure performance limits, keybinding preferences, and UI options

🛠️ Troubleshooting

Common Issues

Keybindings Not Working

Solution: Press EscEsc to focus the main page body and ensure vim navigation is active.

Conflicts with Website Shortcuts

Solution: VimNav automatically disables vim keybindings when you're typing in input fields. If there are conflicts, press i to enter insert mode temporarily.

Extension Not Loading

Solution: Refresh the page, or check that the extension is enabled in Chrome's extension management page.

Performance Issues on Large Pages

Solution: VimNav includes performance limits to prevent browser freezing. Access extension options to adjust limits if needed.

Getting Help

If you encounter issues not covered here: