Find a file
2020-02-08 15:41:27 +00:00
.circleci Fix remaining eval warning in release extension, lint on CI 2019-12-09 21:19:02 +00:00
ci enable server part CI 2019-06-29 15:48:04 +01:00
server Create ~/.config/systemd/user and parent dirs if it does not already exist 2019-12-15 05:51:12 +00:00
src proper implementation for requesting permissions 2020-02-08 15:41:27 +00:00
utils Fix notification in firefox, adapt manifest for chrome 2019-01-28 23:53:41 +00:00
.babelrc set up webpack etc 2019-01-05 10:18:14 +00:00
.eslintrc.js fix eslint, add to ci 2019-01-06 21:00:47 +00:00
.flowconfig notification, proper message routing, etc 2019-01-05 10:18:14 +00:00
.gitignore Add nicer build script 2019-12-09 21:19:02 +00:00
build Allow unsafe eval in dev mode only 2019-12-09 21:58:36 +00:00
LICENSE.md update webpack and version 2019-01-05 13:55:22 +00:00
package.json bump version, add instructions for AMO upload 2019-12-09 21:32:14 +00:00
publish multibuild publish script 2019-01-28 23:53:41 +00:00
quicktest make quicktest executable 2019-11-26 21:18:27 +00:00
README.md bump version, add instructions for AMO upload 2019-12-09 21:32:14 +00:00
TESTING.org Fix notification in firefox, adapt manifest for chrome 2019-01-28 23:53:41 +00:00
TODO.org Update readme 2019-01-27 10:17:56 +00:00
webpack.config.js initial optional permissions support for non-localhost 2020-02-08 15:41:27 +00:00

Build status: CircleCI

Grasp is a browser extension Chrome and Firefox, which adds a button/keybinding to capture current page title and url, possibly selected text, additional comments or tags and adds it into your Org Mode file.

Screenshot, short demo.

Install from Chrome store:

Install from addons.mozilla.org:

Install from a zip: releases.

Running

In the simplest setup, the server runs locally, and you can use 'localhost' version of the extension. If you have to work on a computer where you can't run python scripts, or your target capture file is just not there, you can selfhost the server part elsewhere and use the 'any host' version. Don't forget to set the endpoint in extension settings!

  1. Install server counterpart as systemd service (to autostart it): server/setup --path /path/to/your/capture.org [--port <custom port>] [--template <custom org-capture template>].

    Or alternatively, just run it directly if you don't want to autostart it: server/grasp_server.py --path /path/to/your/capture.org [--port <custom_port>] [--template <custom org-capture template>].

  2. Install chrome extension and configure hotkeys

That's it! If you're using custom port make sure it's same as in the extension settings (default is 12212).

Motivation

Why use org-capture? Well, it's hard to explain, maybe some other time... However if you do know you want to use it instead/alongside your browser bookmarks, by default you don't have much choice and have to copy everything manually. For an experienced enough Org Mode user it's a torture.

For a while, I used the only Chrome extension for that (as for January 2019). However, it relies on setting up MIME handler which is quite flaky for many people (me included). What is more, capturing via org template requires always running emacs daemon, which might be too much for some people. But the worst thing is if capturing fails, you have to way of knowing about it. After losing few days of captured stuff due to MIME handler mysteriously not working, I got fed up and figured it's time to implement something more reliable.

My approach still requires a running server, but it's a simple python script which simply appends a text entry to a text file. The backend always responds back and in case anything fails, you get a notification. There is a collateral benefit though is that you can potentially use anything as a backend and storage file, e.g. you might be more of a Markdown or Todo.txt fan (let me know if you are interested in that!).

Main feature of this extension is that you can also add a comment and tags to the information you are capturing.

The only downside so far is that it's not as well integrated with emacs as its builtin capture templates. E.g. currently you can't point at a specific header in org file, it would just append at the end. However, if that's a stopper for you, please let me know, I could come up with something!

Requirements

No third party dependencies! Just python3.

Potentional improvements

Permissions used

  • storage for settings
  • notifications for showing error notification
  • activeTab for requesting url, title and selected text
  • http://localhost/capture for talking with backend
  • content_security_policy needed for webpack

Building & developing

The most up-to-date instructions should be in CI config.

You're gonna need npm for building extension.

npm install
./build --target <browser> # e.g. ./build --target chrome or ./build --target firefox

After that you can find the extension in dist directory and 'Load unpacked** if necessary. There is also Flow and Eslint set up.

building any host version

If you do need unresticted url permissions, build the extensions like that: ANY_HOST=yes ./build.

testing and linting

Check CI config to figure out all the checks I'm doing.

The only test(s) that don't run on CI at the moment (e.g. due to lack of X server) are marked with @skip_if_ci. You can run them manually though.

Extra tests (not integrated in CI yet):

  • scripts/test_with_browser.py

publishing

  • firefox: ./build --firefox --release --lint && web-ext -s dist build, then upload on AMO

Credits