surfingkeys-conf/README.tmpl.md

Maddy's SurfingKeys Configuration

This is my configuration for the SurfingKeys browser extension.

Its primary features include

• [Site-Specific Key Mappings](#site-specific-key-mappings) which **automate common actions** on many popular websites
• [Search Suggestion Engines](#search-suggestion-engines) providing **interactive search suggestions** from dozens of knowledge sources

Table of Contents

1. Site-Specific Key Mappings
2. Search Suggestion Engines
3. Installation Instructions
4. Screenshots
5. Todo
6. License

Features

Site-Specific Key Mappings

key mappings for unique

sites have been included which can help you perform some common actions:

Search Suggestion Engines

There are currently search suggestion engines.

You can access a search suggestion prompt by pressing the search leader key, which is a by default, followed by the search engine alias.

For example, to open the Wikipedia suggestion engine, you would type awp while in normal mode.

Alias		Name	Domain	Screenshots

Installation

Dependencies

Building surfingkeys-conf requires a few dependencies to be installed:

• Surfingkeys ^0.9.40
• git
• node
• gulp

Building & Installing

1. Clone this repository

   $ git clone http://github.com/b0o/surfingkeys-conf
   $ cd surfingkeys-conf
   

2. Install the NodeJS build dependencies

   $ npm install
   

3. (Optional) Private API Key Configuration

   Some search suggestion engines 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.

   Copy the example private configuration:

   $ cp ./conf.priv.example.js ./conf.priv.js
   

   Open ./conf.priv.js in your favorite editor and follow the instructions inside:

   $ vim ./conf.priv.js
   

4. Gulp Build/Install

   $ gulp install # OR "gulp build" to build to ./build/surfingkeys.js without installing
   

   This will build the final configuration file and place it at ~/.config/surfingkeys.js. If you already have a file in that location, make sure you back it up first!

5. Load your configuration into the SurfingKeys Extension

   Option A (recommended): Configure SurfingKeys to automatically load the configuration file

   Local File Access (Chrome/Chromium only)

   • I. Visit chrome://extensions/ and enable Allow access to file URLs for the Surfingkeys extension.

   • II. Open the SurfingKeys configuration page: chrome-extension://mffcegbjcdejldmihkogmcnkgbbhioid/pages/options.html.

   • III. Set the Load settings from option to point to the configuration file.

     Note: you must specify the full, absolute path; environment variables like $HOME or the tilde ~ won't work:

     • Linux: file:///home/{USERNAME}/.config/surfingkeys.js (replace {USERNAME} with your username)
     • macOS: file:///Users/{USERNAME}/.config/surfingkeys.js (replace {USERNAME} with your username)
     • Windows: file://%Homedrive%%Homepath%/surfingkeys.js (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.

   Local Web Server (Chrome, Chromium, and Firefox)

   • I. Run the configuration file server:

     $ gulp serve-simple
     

     Alternatively, you can use the gulp serve task, which automatically rebuilds the configuration file whenever a source file is modified.

   • II. Open the SurfingKeys configuration page:

     Chrome: chrome-extension://mffcegbjcdejldmihkogmcnkgbbhioid/pages/options.html

     Firefox: moz-extension://7b04efeb-0b36-47f6-9f57-70293e5ee7b2/pages/options.html

   • III. Set the Load settings from option to http://localhost:9919

   • IV. You will want to configure your system to automatically run gulp serve-simple from the repository directory on boot, otherwise SurfingKeys will lose the settings as soon as the local web server is down.

     If you run Linux with systemd, an example user service is provided in this repo. You will need to modify it to contain the proper path to your surfingkeys-conf repo.

   • V. Hack Away! If you ever make a change to any of your configuration files in the future, simply run gulp build again and your new configuration will automatically be loaded by SurfingKeys.

   • Note: This method starts a web server on localhost:9919. Depending on your firewall configuration, other devices on your local network (or the internet at large in the case of misconfigured router firewall) may be able to read your configuration file, including any private API keys or other secrets you have configured in conf.priv.js. Proceed with caution.

   Option B: Manually copy/paste into the SurfingKeys configuration form

   • I. Copy the contents of ./build/surfingkeys.js (or $HOME/.config/surfingkeys.js if you ran gulp install)

   • II. Open the SurfingKeys configuration page:

     Chrome: chrome-extension://mffcegbjcdejldmihkogmcnkgbbhioid/pages/options.html

     Firefox: moz-extension://7b04efeb-0b36-47f6-9f57-70293e5ee7b2/pages/options.html

   • III. Paste into the text box, then press save

   • IV. Repeat steps 4 - 5 after any changes you make to any of your configuration files.

Screenshots

Todo

• Include aliased sites in README
• Add CHANGELOG.md using conventional-changelog
• Improve code organization
• Ensure screenshots have a plain white background
• Add additional screenshots
• Simplify installation process
• Feed the kittens

Copyright