Skip to content

Latest commit

 

History

History
203 lines (128 loc) · 7.69 KB

README.tmpl.md

File metadata and controls

203 lines (128 loc) · 7.69 KB
Raw

Maddison's SurfingKeys Configuration

This is my configuration for the SurfingKeys browser extension.

It includes:

Table of Contents

  1. Site-Specific Key Mappings
  2. Omnibar Search Engine Integrations
  3. Installation Instructions
  4. Screenshots
  5. License

Features

Site-Specific Key Mappings

There are also mappings to open academic papers from 70+ publishers using a DOI handler.

Omnibar Search Engine Integrations

To open the omnibar integration for a search engine, press the search leader key (a by default) followed by the alias for the desired search engine, as found in the table below.

For example, to open the Wikipedia omnibar integration, type awp.

Alias Name Domain Screenshots

∗ requires private API key

† requires local webserver

Installation

Requires Surfingkeys v1.0.0 or newer.

Pre-built

Coming soon!

Build and Install

Dependencies

  • git
  • node.js v17

Procedure

  1. Clone

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

  2. Install Node.js dependencies

    $ npm install

  3. Gulp Build/Install

    $ npm run gulp install # OR "npm run 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!

  4. 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://gfbliohnnapiefjpjlpjnehglfpaknnc/pages/options.html.

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

      Note: you must specify the full, absolute path; the tilde ~ or environment variables like $HOME 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. Repeat these steps after you make any changes to your configuration files. Your new configuration will be automatically loaded by SurfingKeys.

    Local Web Server (Chrome, Chromium, and Firefox)

    • I. Run the configuration file server:

      See Running the Local Web Server

    • II. Open the SurfingKeys configuration page:

      Chrome: chrome-extension://gfbliohnnapiefjpjlpjnehglfpaknnc/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. SurfingKeys will lose the settings as soon as the local web server shuts down. You will likely want to configure your system to automatically start the server on login.

      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. Repeat the npm run gulp build command from step 4 above after you make any changes to your configuration files. Your new configuration will be automatically loaded by the web server and SurfingKeys will pick it up the next time you load a webpage.

    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. Paste the contents into the SurfingKeys configuration page:

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

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

    • III. Repeat these steps after you make any changes to your configuration files. Your new configuration will be automatically loaded by SurfingKeys.

Optional: Private API Key Configuration

Some omnibar search engine integrations require private API keys for access (marked with a ∗ in the table above). These keys are to be defined in ./src/conf.priv.js, which should be created based on the template: ./src/conf.priv.example.js. The template contains instructions on how to generate each API key.

Note: The ./src/conf.priv.js does not exist in the repository, you need to copy the template file. The conf.priv.js should not be commited!

  1. Copy the example private configuration:
$ cp ./src/conf.priv.example.js ./src/conf.priv.js
  1. Open ./src/conf.priv.js in your favorite editor and follow the instructions inside:
$ vim ./src/conf.priv.js

Running the Local Web Server

This project provides a local web server which:

  • Serves your configuration file via HTTP
  • Serves additional API routes for certain search engines, like the unicode search engine.

To run the local web server, follow steps 1-3 in the installation instructions above, then run:

$ gulp serve-simple

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

If you wish to use the local web server, you will likely want it to start automatically with your PC. If you run Linux with systemd, an example user service is provided for this purpose. You will need to modify it to contain the proper path to your surfingkeys-conf repo.

Note: This starts a local web server on localhost:9919 which serves your built configuration file and additional API endpoints. Depending on your firewall configuration, other devices on your network 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.

Screenshots

Copyright