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

🌐 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

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

📑 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 Operations

y Copy selected text to clipboard
Esc Exit visual mode

📍 Marks System

Create bookmarks within pages to quickly jump to specific locations.

Setting Marks

m{a-z} Set a mark at current scroll position (e.g., ma, mb, mc)

Jumping to Marks

'{a-z} Jump to the mark (e.g., 'a, 'b, 'c)
Note: Marks are page-specific and reset when you navigate to a different URL.

⌨️ Command Mode

Execute vim-style commands for advanced browser control and navigation.

Entering Command Mode

: Open command input - type commands and press Enter

Available Commands

:help Show help overlay with all keybindings
:reload Reload current page
:back Go back in browser history
:forward Go forward in browser history
:open {url} Navigate to specified URL
Tip: Commands support tab completion for faster input.

🕰️ History Search

Search and navigate through your browser history with vim-style controls.

History Navigation

H Go back in browser history
L Go forward in browser history

History Search

Use the URL search overlay (o) to search through your browser history:

  • Type keywords to search page titles and URLs
  • Navigate results with j/k
  • Press Enter to navigate to selected history item

⚙️ Extension Configuration

Customize VimNav to match your preferences and workflow.

Accessing Settings

? Open help overlay (includes settings link)

Configuration Options

  • Keybinding Customization - Modify default key mappings
  • Scroll Behavior - Adjust smooth scrolling and scroll distance
  • Hint Appearance - Customize hint styling and colors
  • Site Exclusions - Disable VimNav on specific websites
  • Search Integration - Configure default search engine

🔧 Settings

Detailed settings and customization options for VimNav.

General Settings

  • Enable/Disable - Toggle VimNav on/off globally
  • Scroll Speed - Adjust scrolling sensitivity
  • Smooth Scrolling - Enable/disable smooth scroll animation

Visual Settings

  • Hint Colors - Customize hint appearance
  • Overlay Themes - Choose overlay styling
  • Font Settings - Adjust font size and family for overlays

Advanced Settings

  • Custom CSS - Add custom styling
  • Debug Mode - Enable debugging features
  • Performance - Memory and performance tuning

🛠️ Troubleshooting

Common issues and solutions for VimNav.

Common Issues

VimNav Not Working

  • Check that the extension is enabled in Chrome extensions
  • Verify the site isn't in your exclusions list
  • Try pressing EscEsc to ensure focus

Keybindings Not Responding

  • Make sure you're not in an input field (press Esc)
  • Check for conflicts with other extensions
  • Try refreshing the page

Hints Not Appearing

  • Ensure there are clickable elements on the page
  • Check if the page has custom styling that hides hints
  • Try zooming out if hints are positioned incorrectly

Getting Help

If you continue experiencing issues:

  • Visit our feedback page
  • Check the console for error messages (F12 → Console)
  • Report bugs with specific steps to reproduce