~/vimma/docs $ less start-here.md

Start here

Vimma is a browser for the way you already work. Bare keys drive the page, as in Vim. ctrl+b, tmux's default prefix, drives tabs, panes and workspaces. Your hands stay on the keys, so reading, searching and switching context keep the same flow as your editor and terminal. These pages take you through it in the order you will meet it.

• install and first launch
• learn the modes
• every key

Pick your path

• New to Vim keys

  Start with Modes and Moving around. Five keys take you a long way: j k to scroll, f to follow a link, / to find, Esc to get back.

• Coming from tmux

  The prefix is right where you left it, and ctrl+b c, n, p, v, z, w do what your fingers expect, and ( ) step through workspaces as they step through sessions. Start at The prefix and tabs, then Split panes.

• Coming from Vimium or Tridactyl

  The page keys will feel familiar, and here they also work in the URL bar, on about: pages and in the PDF viewer. Firefox is underneath, so your add-ons come along, now on ctrl+b e. What is new is the window: workspaces, panes and the status bar.

The walk

Each page builds on the one before. The details come from Vimma's own user guide, at the same commit as the keys, so the two always agree.

1. Why Vimma: A browser, not an extension: what that changes for your keys, and what stays Firefox.
2. Vimma compared: Vimium, Tridactyl, qutebrowser and Zen Browser side by side with Vimma: what each does well, and where Vimma differs.
3. Install and first launch: Build Vimma from source on Linux x86_64 and start it with a profile of its own.
4. Modes: Normal, insert, visual, hint and command: how Vimma decides who gets a key.
5. Moving around pages: Scroll, follow links with hints, find text, and go back, forward and reload.
6. The prefix and tabs: ctrl+b, the tab keys, the bindings overlay, the goto picker and tab names.
7. Split panes: Split, move between, zoom, swap and resize panes, as in tmux.
8. Workspaces as containers: Each workspace is a Firefox container: switch, pick, create, rename, delete, move tabs.
9. Routing links to workspaces: Send a site, or every link an app opens, to the workspace it belongs in.
10. The side panel: An on-demand list of the workspace's tabs down the left of the window.
11. Bookmarks: Bookmark a page with ctrl+b a and find it again in a filterable panel.
12. Copy mode: A caret on the page, Vim motions, a selection and y to copy it.
13. config.toml: Options, key bindings and workspaces in one TOML file, reloaded as you save.
14. Firefox's shortcuts: Which Firefox shortcuts Vimma switches off so no key means two things, and how to get them back.
15. Theming: Tokyo Night by default, your own colours in config.toml, or your Omarchy theme, live.
16. Add-ons: Firefox's add-ons, driven from the keyboard: popups, options, enable, remove, updates.
17. Privacy defaults: What Vimma turns off compared with Firefox, what it keeps, and how to change it.
18. Accessibility: Screen readers, focus, announcements, contrast and motion in Vimma's own UI.
19. Scripting with vimma-ctl: Drive a running Vimma from a shell or a window-manager binding, over a local socket.

How keys are written

• ctrl+b v: press ctrl+b, let go, then press v. The status bar shows prefix while it waits.
• gg: two presses of g. G is shift+g.
• <leader>n, in a binding you add: the leader is space, so space then n. It has no default bindings; it is there for yours.
• A count before a key repeats it, as in Vim: 3j scrolls three steps.

Every key is yours

The defaults follow Vim and tmux, but they are a starting point, not a rule. Vimma writes a commented config.toml on its first launch, so the whole format is there to start from. Every binding, the ctrl+b prefix and the space leader can be remapped in ~/.config/vimma/config.toml, by the action names on the keys page. Save the file and Vimma picks it up; a mistake leaves your last working setup in place.

# ~/.config/vimma/config.toml
[keys]
prefix = "ctrl+a"         # the prefix, as tmux users often remap it
new_tab = ["prefix+t"]    # any action, any keys

The leader is leader under [modal]. The whole format is on the config.toml page.

Getting around these pages

This site has a few keys of its own. Press ? for the list. In the docs, ] and [ go to the next and previous page, and / searches every page.