Replace Firefox's default control mechanism with one modelled on the one true editor, Vim.
Installing
Simply click this link in Firefox to install our latest "beta" build. These betas are updated with each commit to master on this repo. Your browser will automatically update from there once a day. If you want more frequent updates, you can change extensions.update.interval
in about:config
to whatever time you want, say, 15 minutes (900 seconds). Alternatively, you can get our "stable" builds straight from Mozilla. The changelog for the stable versions can be found here. If you want to use advanced features such as edit-in-Vim, you'll also need to install the native messenger or executable, instructions for which can be found by typing :installnative
and hitting enter once you are in Tridactyl.
Type :help
or press <F1>
for online help once you're in :)
Remember that Tridactyl cannot run on any page on about:*, data:*, view-source:* and file:*. We're sorry about that and we're working with Firefox to improve this situation by removing restrictions on existing APIs and developing a new API.
We can now run on addons.mozilla.org and a few other websites if you run fixamo
once you've installed the native messenger. help fixamo
tells you exactly what it does.
If you're enjoying Tridactyl, or not, please leave a review on the AMO.
Highlighted features
Like Vim, Tridactyl is modal, with the default mode being "normal mode". In "normal mode", many functions are available using keybindings. In "command mode" (when the command line is shown), you can execute more complex commands, known as "ex-commands". All Tridactyl functionality can be accessed by ex-commands. You can bind any ex-command to a normal-mode shortcut. We also support a .tridactylrc
file, of which there is an example in the root of this repository.
Default normal-mode bindings
This is a (non-exhaustive) list of the most common normal-mode bindings. Type :help
to open the online help for more details.
:
— activate the command lineShift
+Insert
— enter "ignore mode". PressShift
+Insert
again to return to "normal mode".ZZ
— close all tabs and windows, but only "save" them if your about:preferences are set to "show your tabs and windows from last time".
— repeat the last command
You can try :help key
to know more about key
. If it is an existing binding, it will take you to the help section of the command that will be executed when pressing key
. For example :help .
will take you to the help section of the repeat
command.
Navigating with the current page
j
/k
— scroll down/uph
/l
— scroll left/right^
/$
— scroll to left/right margingg
/G
— scroll to start/end of pagef
/F
— enter "hint mode" to select a link to follow.F
to open in a background tab (note: hint characters should be typed in lowercase)gi
— scroll to and focus the last-used input on the pager
/R
— reload page or hard reload pageyy
— copy the current page URL to the clipboard[[
/]]
— navigate forward/backward though paginated pages, for example comics, multi-part articles, search result pages, etc.]c
/[c
— increment/decrement the current URL by 1gu
— go to the parent of the current URLgU
— go to the root domain of the current URLgr
— open Firefox reader mode (note: Tridactyl will not work in this mode)zi
/zo
/zz
— zoom in/out/reset zoom<C-f>
/<C-b>
— jump to the next/previous part of the page
Find mode
Find mode is still incomplete and uses the Firefox feature "Quick Find". This will be improved eventually.
/
— open the find search box<C-g>
/<C-G>
— find the next/previous instance of the last find operation (note: these are the standard Firefox shortcuts)
Please note that Tridactyl overrides Firefox's <C-f>
search, replacing it with a binding to go to the next part of the page. If you want to be able to use <C-f>
again to search for things, use unbind <C-f>
.
Bookmarks and quickmarks
A
— bookmark the current pagea
— bookmark the current page, but allow the URL to be modified firstM<key>
— bind a quickmark to the given keygo<key>
/gn<key>
/gw<key>
— open a given quickmark in current tab/new tab/new window
If you want to use Firefox's default <C-b>
binding to open the bookmarks sidebar, make sure to run unbind <C-b>
because Tridactyl replaces this setting with one to go to the previous part of the page.
Navigating to new pages:
o
/O
— open a URL (or default search) in this tab (O
to pre-load current URL)t
/T
— open a URL (or default search) in a new tab (T
to pre-load current URL)w
/W
— open a URL (or default search) in a new window (W
to pre-load current URL)p
/P
— open the clipboard contents in the current/new tabs
/S
— force a search using the default Tridactyl search engine, opening in the current/new tab. This is useful when searching for something that would otherwise be treated as a URL byo
ort
H
/L
— go back/forward in the tab historygh
/gH
— go to the pages you have set withset home [url1] [url2] ...
Handling tabs
d
— close the current tabu
— undo the last tab/window closuregt
/gT
— go to the next/previous tabg^
/g$
— go to the first/last tabb
— bring up a list of open tabs in the current window; you can type the tab ID or part of the title or URL to choose a tab
Extended hint mode
Extended hint modes allow you to perform actions on page items:
;i
/;I
— open an image (in current/new tab);s
/;a
— save/save-as the linked resource;S
/;A
— save/save-as the selected image;p
— copy an element's text to the clipboard;P
— copy an element's title/alt text to the clipboard;y
— copy an element's link URL to the clipboard;#
— copy an element's anchor URL to the clipboard;r
— read the element's text with text-to-speech;k
— delete an element from the page;;
— focus an element
Additionally, you can hint elements matching a custom CSS selector with :hint -c [selector]
which is useful for site-specific versions of the standard f
hint mode.
Binding custom commands
You can bind your own shortcuts in normal mode with the :bind
command. For example :bind J tabprev
to bind J
to switch to the previous tab. See :help bind
for details about this command.
WebExtension-related issues
- Navigation to any about:* pages using
:open
requires the native messenger. - Firefox will not load Tridactyl on about:*, some file:* URIs, view-source:*, or data:*. On these pages Ctrl-L (or F6), Ctrl-Tab and Ctrl-W are your escape hatches.
- addons.mozilla.org is now supported so long as you run
fixamo
first.
- addons.mozilla.org is now supported so long as you run
- Tridactyl now supports changing the Firefox GUI if you have the native messenger installed via
guiset
. There's quite a few options available, butguiset gui none
is probably what you want, perhaps followed up withguiset tabs always
. See:help guiset
for a list of all possible options.
Frequently asked questions
-
Why doesn't Tridactyl respect my search engine settings?
It used to be a webextension limitation but it's not anymore. There are plans to fix this, see #792.
-
Why doesn't Tridactyl work/why does it break the websites I'm trying to use? or 'Help! A website I use is totally blank when I try to use it with Tridactyl enabled!' or 'Why doesn't Tridactyl work on some pages?'
Please visit our troubleshooting guide.
-
How can I change the search engine?
set searchengine duckduckgo
-
How can I add a search engine?
set searchurls.esa http://www.esa.int/esasearch?q=
You can also add
%s
to specify exactly where the search query should go, which is useful for more inventive uses, such asset searchurls.phrasebook https://translate.google.co.uk/#en/%s/my%20hovercraft%20is%20full%20of%20eels
after which
open phrasebook [fr|de|la|es|hi|it...]
will work as expected. -
Can I import/export settings, and does Tridactyl use an external configuration file just like Vimperator?
Yes, if you have
native
working,$XDG_CONFIG_DIR/tridactyl/tridactylrc
or~/.tridactylrc
will be read at startup via anautocmd
andsource
. There is an example file available on our repository.If you can't use the native messenger for some reason, there is a workaround: if you do
set storageloc local
, a JSON file will appear at<your firefox profile>\browser-extension-data\tridactyl.vim@cmcaine.co.uk\storage.js
. You can find your profile folder by going toabout:support
. You can edit this file to your heart's content. -
How can I change the colors or theme used by Tridactyl?
Use
:colors dark
(authored by @furgerf),:colors shydactyl
(authored by @atrnh) or:colors greenmat
(authored by @caputchinefrobles). Tridactyl can also load themes from disk, which would let you use one of the themes authored by @bezmi (#1012), see:help colors
for more information. -
How to remap keybindings? or How can I bind keys using the control/alt key modifiers (eg:
ctrl+^
)?You can remap keys in normal, ignore, input and insert mode with
:bind --mode=$mode $key $excmd
. Hint mode and the command line are currently special and can't be rebound. See:help bind
for more information.Modifiers can be bound like this:
:bind <C-f> scrollpage 1
. Special keys can be bound too::bind <F3> colors dark
and with modifiers::bind <S-F3> colors default
and with multiple modifiers::bind <SA-F3> composite set hintchars 1234567890 | set hintfiltermode vimperator-reflow
The modifiers are case insensitive. Special key names are not. The names used are those reported by Javascript with a limited number of vim compatibility aliases (e.g.
CR == Enter
).If you want to bind <C-^> you'll find that you'll probably need to press Control+Shift+6 to trigger it. The default bind is which does not require you to press shift.
-
How can I tab complete from bookmarks?
bmarks
. Bookmarks are not currently supported on*open
: see issue #214. -
When I type 'f', can I type link names (like Vimperator) in order to narrow down the number of highlighted links?
You can, thanks to @saulrh. First
set hintfiltermode vimperator
and thenset hintchars 1234567890
. -
Where can I find a changelog for the different versions (to see what is new in the latest version)?
-
Why can't I use my bookmark keywords?
Mozilla doesn't give us access to them. See issue #73.
-
Can I set/get my bookmark tags from Tridactyl?
No, Mozilla doesn't give us access to them either.
-
Why doesn't Tridactyl work on websites with frames?
It should work on some frames now. See #122.
-
Can I change proxy via commands?
Not yet, but this feature will eventually be implemented.
-
How do I disable Tridactyl on certain sites?
You can use
blacklistadd
, like this:blacklistadd mail.google.com/mail
. See:help blacklistadd
. Also note that if you want something like the passkeys or ignorekeys features vimperator/pentadactyl had, you can usebindurl
. See:help bindurl
. -
How can I list the current bindings?
viewconfig nmaps
works OK, but Tridactyl commands won't work on the shown page for "security reasons". We'll eventually provide a better way. See #98. -
How can I know which mode I'm in/have a status line?
Press
j
and see if you scroll down :) There's no status line yet: see #210, but we do have a "mode indicator" in the bottom right. It even goes purple when you're in a private window :). -
Does anyone actually use Tridactyl?
In addition to the developers, some other people do. Mozilla keeps tabs on stable users here. The maintainers guess the number of unstable users from unique IPs downloading the betas each week when they feel like it. Last time they checked there were 2200 of them.
-
How do I prevent websites from stealing focus?
There are two ways to do that, the first one is
set allowautofocus false
(if you do this you'll probably also want to setbrowser.autofocus
to false inabout:config
). This will prevent the page'sfocus()
function from working and could break javascript text editors such as Ace or CodeMirror. Another solution is to useautocmd TabEnter .* unfocus
in the beta, JS text editors should still work but pages won't steal focus when entering their tabs anymore.
Contributing
Donations
We gratefully accept donations via PayPal. If you can, please make this a monthly donation as it makes it much easier to plan.
Funds will be used at the discretion of the main contributors (currently bovine3dom, cmcaine, glacambre and antonva) for Tridactyl-related expenditure, such as domain names, server costs, small thank-yous to contributors such as stickers, and victuals for hackathons.
Building and installing
Onboarding:
git clone https://github.com/tridactyl/tridactyl.git
cd tridactyl
npm install
npm run build
Each time package.json or package-lock.json change after you checkout or pull, you should run npm install
again.
Addon is built in tridactyl/build. Load it as a temporary addon in firefox with about:debugging
or see Development loop. The addon should work in Firefox 52+, but we're only deliberately supporting >=57.
If you want to install a local copy of the add-on into your developer or nightly build of firefox then you can enable installing unsigned add-ons and then build it like so:
# Build tridactyl if you haven't done that yet
npm run build
# Package for a browser
"$(npm bin)/web-ext" build -s build
If you want to build a signed copy (e.g. for the non-developer release), you can do that with web-ext sign
. You'll need some keys for AMO and to edit the application id in src/manifest.json
. There's a helper script in scripts/sign
that's used by our build bot and for manual releases.
Building on Windows
-
Install Git for Windows
-
Install NodeJS for Windows
- Current 8.11.1 LTS seems to work fine
-
Launch the installation steps described above from MinTTY shell
- Also known as "Git Bash"
Development loop
npm run build & npm run run
You'll need to run npm run build
every time you edit the files, and press "r" in the npm run run
window to make sure that the files are properly reloaded.
Committing
A pre-commit hook is added by npm install
that simply runs npm test
. If you know that your commit doesn't break the tests you can commit with git commit -n
to ignore the hooks. If you're making a PR, travis will check your build anyway.
Documentation
Ask in #tridactyl
on matrix.org, freenode, or gitter. We're friendly!
Default keybindings are currently best discovered by reading the default config.
Development notes are in the doc directory, but they're mostly out of date now. Code is quite short and not too badly commented, though.
Principles and objectives
Principles:
- Keyboard > mouse
- default keybinds should be Vim-like
- actions should be composable and repeatable
- ex mode should expose all the browser functionality anyone might want
- Arguable: most (all?) actions should have an ex mode version (departure from Vim?)
- users can map and define their own actions and commands
Other objectives:
- be fast - the whole point of a keyboard interface is to be more efficient, don't compromise that with slow code
- don't crash - we're the new UI and we shouldn't crash
- be maintainable - code should be well documented, reasoned about and tested.
Logo acknowledgement
The logo was designed by Jake Beazley using free vector art by www.Vecteezy.com