Find a file
Dima Gerasimov 694f577363 bump version
2020-02-08 16:30:13 +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 add a prompt for manual test 2020-02-08 15:41:27 +00:00
src Display permission status for the endpoint 2020-02-08 15:41:27 +00:00
utils remove ANY_HOST stuff 2020-02-08 16:28:37 +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 2020-02-08 16:30:13 +00:00
publish remove ANY_HOST stuff 2020-02-08 16:28:37 +00:00
quicktest make quicktest executable 2019-11-26 21:18:27 +00:00
README.md remove ANY_HOST stuff 2020-02-08 16:28:37 +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 remove ANY_HOST stuff 2020-02-08 16:28:37 +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 the 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 of/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 no less than a torture.

This tool:

  • + shows a notification when capturing fails/succeeds, so you won't lose your notes

  • + doesn't require always running Emacs, simply appends an org-mode text entry to a file

  • + can capture things that org-protocol can't handle (e.g. extra comment or tags)

  • + can potentially use any plaintext format as a storage.

    E.g. you might be more of a Markdown or Todo.txt fan (let me know if you are interested in that!).

  • - doesn't talk to Emacs, so can't benefit from Emacs capture templates

    E.g. currently you can't point at a specific header in an org file, it would just append at the end.

  • - requires running a small HTTP server

    However, there are no dependencies apart from python3, so in many ways, it's even more portable than Emacs.

Comparison with similar tools:

org-capture-extension

  • - relies on org-protocol and MIME handler: flaky for many people and has no feedback whether capture failed or succeeded

    Losing few days of captured stuff due to MIME handler mysteriously not working was the main motivator for me to develop grasp.

  • - requires always running Emacs, which might not be the case for some people

  • + relies on org-protocol, so can potentially be better integrated with Emacs and your org-mode files

org-protocol-capture-html

Same pros/cons as org-capture-extension as it's relying on org-protocol.

In addition:

  • + using a bookmarklet, hence browser-agnostic
  • + capable of on the fly HTML to org-mode markup conversion

Requirements

No third party dependencies! Just python3.

Potential improvements

Permissions used

  • http://localhost/capture for talking with the backend

    If you want to use an external URL as an endpoint, you will be prompted for a permission dynamically.

  • storage for settings

  • notifications for showing notification

  • activeTab for requesting page info

Building & developing

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

You need npm for building the 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.

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