Home

Awesome

<h1 align="center"> <br> <img src="src/static/logo/Tridactyl_200px.png" alt="Tridactyl Logo" width="200"> <br> Tridactyl <br> </h1> <h4 align="center">Replace Firefox's default control mechanism with one modelled on the one true editor, Vim.</h4> <p align="center"> <a href="https://travis-ci.org/tridactyl/tridactyl"><img src="https://travis-ci.org/tridactyl/tridactyl.svg?branch=master" alt="Build Status"></a> <a href="https://matrix.to/#/#tridactyl:matrix.org"><img src="https://img.shields.io/badge/matrix-join%20chat-green" alt="Matrix Chat"></a> <a href="https://gitter.im/tridactyl/Lobby"><img src="https://badges.gitter.im/Join%20Chat.svg" alt="Join Gitter Chat"></a> <a href="https://discord.gg/DWbNGTAvmh"><img src="https://img.shields.io/discord/854326924402622474?color=%235865F2&label=discord" alt="Join Discord Chat"></a> <a href="https://addons.mozilla.org/en-US/firefox/addon/tridactyl-vim/"><img src="https://img.shields.io/amo/rating/tridactyl-vim" alt="Mozilla Addon Store"></a> </p> <p align="center"> <a href="#installation">Installation</a> • <a href="#changelog">Changelog</a> • <a href="#first-look">First Look</a> • <a href="#highlighted-features">Features</a> • <a href="#frequently-asked-questions-faq">FAQ</a> • <a href="#contributing">Contributing</a> </p> <br> <p align="center"> <img src="doc/AMO_screenshots/trishowcase.gif" alt="Tridactyl GIF"> </p>

Installation

Click this link in Firefox to install our latest "beta" build. If it doesn't install automatically, you may need to 1) rename the extension from .zip to .xpi and 2) open it with Firefox; a fool-proof method is to go to about:addons, click the extensions tab, click the cog in the top right, then click "Install Add-on From File...". If you want more options, read on.

Stable

Our "stable" builds are essentially just frozen versions of our beta builds. Our beta builds themselves are not much less stable; all our developers and about half of our users use the beta builds. Stable builds, however, do get new features documented in the changelog, whereas beta builds get new features before they are documented there.

Arch Linux

Run pacman -S firefox-tridactyl in a terminal and then restart Firefox twice.

All other operating systems (Microsoft Windows, Macintosh, Linux etc.)

Tridactyl stable can be installed from the Mozilla add-ons website (the AMO).

Beta

Click this in Firefox to install our "beta" builds. These betas used to be updated with each commit to master on this repo but are now built manually when bovine3dom remembers - see issue #3605. 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). There is also another beta build that comes without a new tab page. You can get it from here.

Extra features through Native Messaging

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. Arch users can install the AUR package firefox-tridactyl-native instead.

Containerized/sandboxed Firefox Installations

Snap and Flatpak: Native Messaging support here is fairly recent and may require:

See this call for testing thread and this PR for more details and troubleshooting tips.

Firejail will require explicit path whitelisting, but should be feasible based on https://github.com/netblue30/firejail/issues/2109.

For other containerized installs, see troubleshooting steps in https://github.com/tridactyl/tridactyl/issues/2406 and the links above. With packaging that does support Native Messaging, the trick is usually ensuring the containerized app has permission to run the executable and can find the manifest json file.

Migrating between beta and stable builds

Our beta and stable versions store their configurations in separate places. To migrate between the two, see the wiki.

Changelog

The changelog for the stable versions can be found here.

First look

Type :help or press <F1> for online help once you're in, or :tutor for a friendly introduction. You might also find the unofficial Tridactyl Memrise course (requires login) useful for memorising keybinds.

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.

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.

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

Find mode

Find mode is still incomplete and uses the Firefox feature "Quick Find". This will be improved eventually.

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> to search for things, use <C-f> after opening the Quick Find box (/), or any input field such as the address bar or search bar (use default browser shortcuts to activate these). To allow usage of <C-f> at any time, use unbind <C-f> to unset the scrollpage binding.

Bookmarks and quickmarks

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.

Marks

Navigating to new pages:

Handling tabs

Extended hint mode

Extended hint modes allow you to perform actions on page items:

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

Frequently asked questions (FAQ)

Contributing

Donations

We gratefully accept donations via GitHub Sponsors (we receive 100% of your donation), PayPal (about 70% of your donation makes it to our bank account after fees) and Patreon (about 70% of your donation makes it to our account). If you can, please make this a monthly donation as it makes it much easier to plan. People who donate more than 10USD a month via GitHub or Patreon get a special monthly "tips and tricks" newsletter - see an example here. All GitHub and Patreon donors get a quarterly newsletter on Tridactyl development.

<a href="https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=7JQHV4N2YZCTY"><img src="https://www.paypalobjects.com/en_US/GB/i/btn/btn_donateCC_LG.gif" alt="PayPal"></a>

Funds currently ensure that bovine3dom can afford to work on Tridactyl about one day a week.

Merchandise

We have some designs available on REDBUBBLE. There are often discount codes available - just search your favourite search engine for them. The T-shirts are quite good (I'm wearing one as I type this). The stickers are not the best quality we've ever seen. The clock looks amazing on the website. If anyone buys it I would love to see it.

We don't take any cut from the merchandise, so if you would like to donate, please do so via PayPal or Patreon above.

Building and installing

Onboarding:

git clone https://github.com/tridactyl/tridactyl.git
cd tridactyl
yarn install
yarn run build

Each time package.json or yarn.lock change after you checkout or pull, our git hook will try to run yarn install again. If it doesn't you should do it manually.

Addon is built in build/. Load it as a temporary addon in firefox with about:debugging or see Development loop.

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
yarn run build
# Package for a browser
scripts/sign nosignbeta

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.

You can build unsigned copies with scripts/sign nosign{stable,beta}. NB: The stable versus beta part of the argument tells our build process which extension ID to use (and therefore which settings to use). If you want a stable build, make sure you are on the latest tag, i.e. git checkout $(git tag | grep '^[0-9]\+\.[0-9]\+\.[0-9]\+$' | sort -t. -k 1,1n -k 2,2n -k 3,3n | tail -1).

If you are on a distribution which builds Firefox with --with-unsigned-addon-scopes= set to app and/or system (which is most of them by users: Arch, Debian, Ubuntu), you can install your unsigned copy of Tridactyl with scripts/install.sh [directory]. If you're on Arch, the correct directory is probably selected by default; on other distributions you might have to go hunting, but it probably looks like /usr/lib/firefox/browser/extensions.

Building on Windows

Development loop

yarn run build & yarn run run
<!-- This will compile and deploy your files each time you save them. -->

You'll need to run yarn run build every time you edit the files, and press "r" in the yarn run run window to make sure that the files are properly reloaded.

You can speed up the build process after your first build by using yarn run rebuild instead. This skips rebuilding the metadata (used in completions), documentation, new tab page, and tutor, so don't use it if that's what you're trying to test.

Committing

A pre-commit hook is added by yarn install that simply runs yarn 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, Libera, gitter, or Discord. 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:

Other objectives:

Logo acknowledgement

The logo was designed by Jake Beazley using free vector art by <a target="_blank" href="https://www.Vecteezy.com">www.Vecteezy.com</a>