2017-12-02 03:10:34 +00:00
<!-- {{DISCLAIMER}} -->
2018-08-23 09:10:58 +00:00
2018-11-28 00:38:53 +00:00
[![Commitizen friendly ](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg?style=for-the-badge )](http://commitizen.github.io/cz-cli/)
[![Liberapay contributions ](https://img.shields.io/liberapay/receives/b0o.svg?logo=liberapay&style=for-the-badge )](https://liberapay.com/b0o/donate)
2018-11-21 13:15:06 +00:00
Maddy's SurfingKeys Configuration
=================================
2017-10-31 05:39:21 +00:00
2018-08-09 23:45:55 +00:00
This is my personal configuration for the wonderful [SurfingKeys ](https://github.com/brookhong/Surfingkeys ) browser extension.
2017-10-31 05:39:21 +00:00
2018-08-23 10:47:38 +00:00
Its primary features include [keybindings for performing common actions ](#site-specific-key-mappings ) on many popular
2018-11-05 06:40:27 +00:00
sites, as well as OmniBar support for [auto-completing searches ](#bundled-search-engine-completions ) within <!--{{COMPL_COUNT}}--> sites (and growing)!
2018-08-23 10:47:38 +00:00
Table of Contents
-----------------
2018-08-23 11:09:43 +00:00
1. [Site-Specific Key Mappings ](#site-specific-key-mappings )
2. [Bundled Search Engine Completions ](#bundled-search-engine-completions )
2018-08-23 11:08:21 +00:00
3. [Installation Instructions ](#installation )
2018-08-23 10:47:38 +00:00
4. [Screenshots ](#screenshots )
2018-08-23 11:08:21 +00:00
5. [Todo ](#todo )
6. [License ](#license )
2018-08-23 10:47:38 +00:00
Features
2018-08-23 11:08:21 +00:00
--------
2018-08-23 10:47:38 +00:00
### Site-Specific Key Mappings
2017-10-31 05:39:21 +00:00
2018-11-10 01:47:39 +00:00
<!-- {{KEYS_MAPS_COUNT}} --> key mappings for <!-- {{KEYS_SITES_COUNT}} --> unique
sites have been included which can help you perform some common actions:
2017-10-31 05:39:21 +00:00
2018-11-10 01:47:39 +00:00
< table >
< tbody >
<!-- {{KEYS_TABLE}} -->
< / tbody >
< / table >
2018-08-23 10:47:38 +00:00
### Bundled Search Engine Completions
2017-10-31 05:39:21 +00:00
2017-12-02 03:10:34 +00:00
There are currently <!-- {{COMPL_COUNT}} --> Search Engine auto-completions.
2017-10-31 05:39:21 +00:00
2017-10-31 05:45:03 +00:00
You can access a Search Engine auto-completion by pressing the search leader key, which is `a` by default, followed by the search engine alias.
2017-10-31 05:39:21 +00:00
For example, to open the Wikipedia completion, you would type `awp` while in normal mode.
2019-03-10 03:28:48 +00:00
< table >
< thead >
< th colspan = 2 > Alias< / th >
< th > Name< / th >
< th > Domain< / th >
< th > Screenshots< / th >
< / thead >
< tbody >
<!-- {{COMPL_TABLE}} -->
< / tbody >
< / table >
<!--
2017-11-17 14:31:29 +00:00
| Alias | Name | Domain | Screenshots |
2018-11-10 01:47:39 +00:00
| ----- | ---- | ------ | ----------- |
2019-03-10 03:28:48 +00:00
-->
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
Installation
------------
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
### Dependencies
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
Building `surfingkeys-conf` requires a few dependencies to be installed:
2017-10-31 05:39:21 +00:00
2018-11-20 01:08:03 +00:00
- __Surfingkeys__ `^0.9.40`
2018-11-03 00:20:28 +00:00
- __git__
- __node__
- __gulp__
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
### Building & Installing
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
1. __Clone this repository__
```shell
$ git clone http://github.com/b0o/surfingkeys-conf
$ cd surfingkeys-conf
```
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
2. __Install the NodeJS build dependencies__
```shell
$ npm install
```
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
3. __ *(Optional)* Private API Key Configuration__
2018-08-23 10:47:38 +00:00
2018-08-23 11:08:21 +00:00
Some Search Engine Auto-Completions require private API keys for access. These
keys are defined in `conf.priv.js` , which is not itself included in this repository.
An example configuration containing instructions on how to generate each API key
can be found in [conf.priv.example.js ](./conf.priv.example.js ).
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
Copy the example private configuration:
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
```shell
$ cp ./conf.priv.example.js ./conf.priv.js
```
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
Open `./conf.priv.js` in your favorite editor and follow the instructions inside:
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
```shell
$ vim ./conf.priv.js
```
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
4. __Gulp Build/Install__
```shell
$ gulp install # OR "gulp build" to build to ./build/.surfingkeys without installing
```
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
This will build the final configuration file and place it at `~/.surfingkeys` .
If you already have a file in that location, make sure you back it up first!
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
5. __Load your configuration into the SurfingKeys Extension__
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
< details >
< summary > < strong > Option A< / strong > < em > (recommended)< / em > : Configure SurfingKeys to automatically load configuration file from disk< / summary >
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __I.__ Visit [`chrome://extensions/` ](chrome://extensions/ ) and enable `Allow access to file URLs` for the Surfingkeys extension
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __II.__ Open the SurfingKeys [configuration page ](chrome-extension://mffcegbjcdejldmihkogmcnkgbbhioid/pages/options.html )
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __III.__ Set the `Load settings from` option to point to the configuration file.
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
_Note: you must specify the full, absolute path; environment variables like `$HOME` or the tilde `~` won't work_ :
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
- __Linux__: `file:///home/{USERNAME}/.surfingkeys` (replace `{USERNAME}` with your username)
- __macOS__: `file:///Users/{USERNAME}/.surfingkeys` (replace `{USERNAME}` with your username)
- __Windows__: `file://%Homedrive%%Homepath%/.surfingkeys` (This is a guess, please correct me if I'm wrong)
- __IV.__ Hack Away! If you ever make a change to any of your configuration files in the future, simply run `gulp install` again and your new configuration will automatically be loaded by SurfingKeys.
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
< / details >
2017-10-31 05:39:21 +00:00
2018-08-23 11:08:21 +00:00
< details >
< summary > < strong > Option B< / strong > : Manually copy/paste into the SurfingKeys configuration form< / summary >
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __I.__ Copy the contents of `./build/.surfingkeys` (or `$HOME/.surfingkeys` if you ran `gulp install` )
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __II.__ Open the SurfingKeys [configuration page ](chrome-extension://mffcegbjcdejldmihkogmcnkgbbhioid/pages/options.html )
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __III.__ Paste into the text box, then press `save`
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
- __IV.__ Repeat steps 4 & 5 after any changes you make to any of your configuration files.
2018-08-27 07:18:02 +00:00
2018-08-23 11:08:21 +00:00
< / details >
2018-08-18 23:32:36 +00:00
2018-08-23 11:08:21 +00:00
Screenshots
-----------
2017-12-02 03:10:34 +00:00
<!-- {{SCREENSHOTS}} -->
2017-10-31 06:56:35 +00:00
2018-08-23 11:08:21 +00:00
Todo
----
2017-11-17 15:49:48 +00:00
2018-08-23 09:44:54 +00:00
- [ ] Add `CHANGELOG.md` using [conventional-changelog ](https://github.com/conventional-changelog/conventional-changelog )
2017-11-17 15:49:48 +00:00
- [ ] Improve code organization
- [ ] Ensure screenshots have a plain white background
- [ ] Add additional screenshots
2018-08-23 10:47:38 +00:00
- [x] Simplify installation process
2017-11-17 15:49:48 +00:00
- [x] Feed the kittens
2018-08-23 11:08:21 +00:00
License
-------
2018-08-09 23:45:55 +00:00
© 2017-2018 Maddison Hellstrom - MIT License