Introduction

Vimperator is a plugin for Firefox that makes the user interface Vim-alike: it introduces many of the Vim UI concepts so that the browser becomes predominantly keyboard driven. If you love Vim's keyboard driven navigation then making the browser a comfortable experience is worthwhile. If you don't already know Vim then it's unlikely to be of interest as Vimperator substantially changes the UI. Newer versions of Vimperator seem to over ride fewer of the standard keys than previously (e.g. ctrl-t works), but it's still a considerable change. It's like Marmite!

Figure 1: Vimperator - History list

Figure 1 Shows Vimperator running, the bottom command-line bar is displaying some actions in green text (e.g Space). The main window is displaying the history list, both the URL and the title of the page. The top shows the tabs with small numbers on each which let me use a keyboard short cut to easily switch between them. I've kept the menus but notice that the location bar, and the scrollbars have been removed to optimise the space. The look and feel is fully customisable through a theme.

If you're using Firefox the alternative is Pentadactyl, though in 2016 this is less maintained. If you're using Chrome or Chromium then Vimium is a similar plugin.

As the plugin makes substantial changes to the interface it interacts with Firefox a lot. There are conflicts with different versions of Firefox and a number of elements didn't work for me. For comparison purposes, (using the command :version), I'm on:

Vimperator: 3.14.0 (created: 2016/06/07 23:58:16)
Firefox:    Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:47.0) Gecko/20100101 Firefox/47.0

The key to understanding Vimperator is the mental model. It's trying to bring Vim modes (Normal mode, Insert modes) to the browser and you have to think of these in the context of the different activities we do in a browser (browsing, viewing the current page, tab management). The help is very extensive (:help) and worth reading.

Modes and interaction

Normally interacting with Firefox involves using the menus at the top, the location bar or other dialogs, and the mouse for context menus. With Vimperator many of these UI elements remain (e.g. menus and mouse context menus) but the focus moves to interacting through the keyboard.

Vimperator provides a comprehensive set of keyboard shortcuts which the next sections document. Additionally, it adds a bar across the bottom which is interacted with using vim-like commands. Anyone whose used Vim will be familiar with this modal method of interacting. Many of the commands are documented in the Command mode sections. The shortest version of the command is shown before the square brackets that document additional letters than can be typed - tab completion also works.

Broadly, these notes follow the help documentation (:help) structure, they don't cover everything, just the things that were important to me.

Browsing

This section covers the main activities when you're browsing a page. Typically, it's the basics like opening URL's, tabs and history management which you normally access through Firefox menus or the navigation bar.

Current tab (buffer)

Navigating within a page, which Vimperator calls a buffer. As with Vim buffers there are a lot of methods for moving through the document. The main surprise I found was text copy and paste, as y copies the URL, to copy some highlighted text use Y. Note that <ctrl>-c and <ctrl>v still work, if you're used to them.

Tab management

Figure 2: Vimperator - Buffer list

Vimperator thinks of tabs as buffers in the vim manner. There are a variety of ways to change between them and reorganise them using keyboard shorts cuts and command line commands. Figure 2 shows a buffer list being displayed through the ls command.

One tip is to use the Local Marks A-Z to mark a tab (:ma A) and switch to it with 'A in any tab - provides a nice way to switch between specific locations on tabs.

The most important commands are in the table below. Vimperator also lets you manage tab groups, but I've skipped that as I don't use them (see help tab).

Command-line mode

Command-line mode is for entering ex commands and text search patterns. All the commands are input with a colon (:) at the start in the same manner as Vim.

Hints - Link mode

Figure 3: Vimperator - Hints displaying links

Hints are a fantastic navigation method where each link is highlighted (hinted) with a letter or number. Hitting the corresponding letter follows the link. Enter f (follow link), F (follow link in new tab) and it will hint all the links.

A bit hard to explain, Figure 3 shows an example where each link is hinted with a large letter on a red background block. The size and colour of the hints can be changed in the theme configuration. The default is to show hints as numbers, but this can be configured through the hintchars variable, which I've set to characters as these are easier to type.

When a hint is highlighted, we can interact with the link by typing:

1. The number/letter hint
2. Part of the name
3. Part of the name and <tab> for completion

Marks

Vimperator supports a range of different marks:

• Bookmarks - standard bookmarks
• QuickMarks allow you to define up to 62 (a-zA-z0-9) web sites that you access commonly
• Local marks to store the position within a web page
• History is a special type of mark.

Personally, I find bookmarks more useful as they're easier to handle (I haven't documented all the commands here), and the QuickMarks capability is very interesting.

qmark h https://news.ycombinator.com/

Insert mode - Forms

Insert mode happens when you're in a form, there are other key bindings, but the main one for me is being able to start Vim locally with the contents:

We can set the editor with something like:

" define the editor
set editor="/usr/bin/gvim -f"
" call with <leader>i as well as Ctrl-i as Ctrl-i is sometimes over-ridden
inoremap <Leader>i <C-i>

Key mappings

The key mapping commands can be used to redefine either standard key bindings or define new ones (:help mapping). Keys can be mapped in four modes:

• Normal mode: When browsing normally
• Visual mode: When selecting text with the cursor keys
• Insert mode: When interacting with text fields
• Command-line mode: When typing into the Vimperator command line

" Create a map for F2 which calls the Javascript for date
:map <F2> :echo new Date().toDateString()<CR>

" Create two maps so that g1 and g3 call tabs 1 and 3 respectively
" The second map is silent so nothing is echoed to the Command line
:map g1 :tabn 1<CR>
:map <silent> g3 :tabn 3<CR>

" https://github.com/vimperator/vimperator-labs/issues/10
" To Enable map <Space>
js <<EOM
  window.addEventListener('keypress',function (event) {
    var code=event.charCode;
    if ((liberator.mode === modes.INSERT && modes.extended === modes.MENU)
    ||(liberator.mode ==modes.NORMAL && code==32)
    ||(liberator.mode ==modes.COMMAND_LINE && code !=32)){
      let map = mappings.get(liberator.mode, events.toString(event));
      if (map) {
        event.preventDefault();
        event.stopPropagation();
        map.execute();
      }
    }
  },false);
EOM

" My Customization
map <Space> <Leader>

" Add the command :close to close a tab
:command close :bd
" Add the command :Google to open the supplied args at google.com
:command -nargs=* Google open google <args>

Configuration

Configuration is stored in ~/.vimperatorrc. To create an initial configuration file use :mkv. If you're playing with settings then do source ~/.vimperatorcc, if new extensions are also being loaded then the browser needs to be restarted with :res[tart].

Each option can be set on the command-line or in the configuration file, as follows:

set option=values
set gui=menu,tabs

The help file for options (:help options) is very complete, to see the current options do :set. The most important for me are:

Current configuration:

" To enable mapping <Space>
js <<EOM
  window.addEventListener('keypress',function (event) {
    var code=event.charCode;
    if ((liberator.mode === modes.INSERT && modes.extended === modes.MENU)
    ||(liberator.mode ==modes.NORMAL && code==32)
    ||(liberator.mode ==modes.COMMAND_LINE && code !=32)){
      let map = mappings.get(liberator.mode, events.toString(event));
      if (map) {
        event.preventDefault();
        event.stopPropagation();
        map.execute();
      }
    }
  },false);
EOM

" Map spacebar to be leader
map <Space> <Leader>

" Maps
" map <F2> :echo<Space>new<Space>Date().toDateString()<Return>
map <silent> <Leader>1 :tabn<Space>1<Return>
map <silent> <Leader>2 :tabn<Space>2<Return>
map <silent> <Leader>3 :tabn<Space>3<Return>
map <silent> <Leader>4 :tabn<Space>4<Return>
map <silent> <Leader>5 :tabn<Space>5<Return>
map <silent> <Leader>6 :tabn<Space>6<Return>
map <silent> <Leader>7 :tabn<Space>7<Return>
map <silent> <Leader>8 :tabn<Space>8<Return>
map <silent> <Leader>9 :tabn<Space>9<Return>
map <silent> <Leader>0 :tabn<Space>10<Return>

" Make it easy to move between tabs
map <Leader>l :tabnext<Return>
map <Leader>h :tabprevious<Return>

" Add the command :close to close a tab
:command -description "Closing tab" close :bd

" Stop d from closing a tab as this is a Vim command
" Use :bd
map d <Nop><Return>

" Remove scrollbars
:set scrollbars=false

" Improve scrolling for <ctrl>d and <ctrl>u
" :set scroll=3
" Improve general scrolling: j jjj is an alternative
" https://github.com/vimpr/vimperator-plugins/blob/master/_smooziee.js is an alternative
:noremap j 3j
:noremap k 3k

" GUI configuration
" Show menus and tabs, but not the navigation bar.
:set gui=menu,tabs
:set toolbars=nonavigation

" Show small numbers on the tabs to ease navigation
:set tabnumbers=true

" Make the default search engine for 'o' duckduckgo
:set defsearch=duckduckgo

" QuickMarks: go<letter>
qmark h https://news.ycombinator.com/
qmark n https://newsblur.com

" Colour - Molokai with a couple of adjustments
colorscheme molokai
hi CmdLine color: #aaa; background: #333; font-size: 14px; font-weight: normal; font-family: Ubuntu; padding: 0px; vertical-align: middle; border: none;
hi Hint -append font-size: 150%;

" Change hints to letters that are easy to type and numbers
set hintchars=jkhlasdfgyuiopqwertnmzxcvb1234567890

" Source in any local changes
source! /home/steve/.vimperatorrc.local

" vim: set ft=vimperator:

Plugins

Vimpr is a repository of plugins for Vimperator. Plugins are loaded as follows:

• Find the plugin you want.

  There are 162 plugins to choose from currently!

• Download and copy it to ~/.vimperator/plugin/

  Note that you don't have to add them explicitly in the RC file.

• Configure the plugin

  Some have configuration parameters that can be added to the RC file.

• Reload Firefox

  Rather than restarting you can :source ~/.vimperatorrc

You can see what's been loaded with :scriptnames

" Don't use keys for some sites
:ignorekeys add https://gmail.com/
":ignorekeys --except= https://mail.google.com/
":autocmd LocationChange mail\\.google\\.com :set editor=gvim -f -c 'set ft=mail'

" Libly must be loaded before other plugins
:source ~/.vimperator/plugin/_libly.js
command! -nargs=+ lazy autocmd VimperatorEnter .* <args>
lazy fmaps -u='mail.google.com/mail' c / j k n p o u e x s r a # [ ] ? gi gs gt gd ga gc
lazy fmaps -u='mail\.google\.com/mail/.*/[0-9a-f]+$' c / j,n k,p n,j p,k o u e x s r a # [ ] ? gi gs gt gd ga gc
lazy fmaps -u='github\.com/[^/]+/.+' -events=vkeydown s,t gc gi gp gw
lazy fmaps -u='duckduckgo\.com/\?q=' -events=vkeydown l j k <enter> s,d gm,m gt,t
lazy fmaps -u 'www\.google\.com/calendar -events=vkeypress j k T,t a D,d w m x c e z / + q s ?
lazy fmaps -u='calendar\.google\.com/.*' -events=vkeypress k p j n r t 1 d 2 w 3 m 4 x 5 a c e <backspace> <delete> <ctrl> z s / <shift> = + q ?

Colours and Fonts

It's worth checking the font that's being used in Firefox through the preferences dialog. I changed mine to Ubuntu as by default Vimperator will use the default Mono font.

Vimperator has many of the configuration parameters you'd expect for setting fonts, colours and changing aspects of the interface. For color themes the easiest way is to look at the repository:

• Find the colour scheme that you want.

  The vimperator color repository is the best option.

• Download and install it to ~/.vimperator/colors/

  Don't forget to grab it in raw form!

• Configure it in your ~/.vimperatorcc

  On the command line do :colorscheme <name> for testing, it will provide auto-completion for what's available as soon as there's a space.

• Restart Firefox

  Restart to test that the configuration is working, or do :source ~/.vimperatorrc

NOTE: Molokai is available on pschmitt's github, thanks to Vimperator tips and tricks for the pointer!

Example configurations

• Igal vimperatorrc gist
• Standard configurations
• Simple default configuration
• Nicely commented vimperatorrc
• Yym configuration gist
• Extensive blog post in Japanese covering configuration

Firefox configuation

A side-benefit of using Vimperator is that you can define Firefox configuration in a text file. The Arch Wiki has some useful configuration tweaks. The settings I used are:

" Firefox settings
" GPU accelerated rendering
set! layers.acceleration.force-enabled=true
set! layers.offmainthreadcomposition.enabled=true
" Improve network performance
set! network.http.pipelining=true
" Save session every 60 seconds, default every 15 seconds
set! browser.sessionstore.interval=60000

Vimperator resources and footnotes

• Vimperator on Github

  Project page on Github, the Issues are worth browsing through for tips.

• Vimperator plugins

  Plugins on github, clearly popular in the Japanese community.

• Vimperator Google group

  Mailing list for tips and developers

• How to control Firefox using Vim keybindings

  Keybindings and limitations have changed a lot since this was written, but it's a nice overview.

• Weekend project: Add Vim features to Firefox with Vimperator

  Introductory article on Vimperator. It's a bit out of date but a great intro nevertheless.

• Vimperator interface for Firefox: Part 1

  Series of blog posts on using Vimperator.

• Pentadactyl vs Vimperator

  The project diverged at one point in the past, this seems to cover why.

• Use Firefox the vim way

  Out of date, but good article on using Vimperator.

• Vimperator tips and tricks

  Good post on some tips and tricks.

• Vimperator cheat sheet

  One pager with all the most important commands on it.

Comments

If you have comments or questions about Vimperator please comment below!