karlicoss / grasp Goto Github PK

A reliable org-capture browser extension for Chrome/Firefox

Home Page: https://beepb00p.xyz/grasp.html

License: MIT License

JavaScript 20.66% Shell 1.42% Python 53.24% HTML 1.85% TypeScript 22.83%

capture org-capture org-mode pkm browser-extension annotation chrome-extension firefox-extension webext

grasp's Introduction

Grasp is a browser extension for 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.

Chrome
Firefox
or, 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. Don't forget to set the endpoint in extension settings!

Setup

install grasp_backend package: pip3 install --user grasp-backend
install systemd/launchd service to autorun grasp

python3 -m grasp_backend 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 python3 -m grasp_backend serve --path /path/to/your/capture.org [--port <custom port>] [--template <custom org-capture template>]
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).

Configuration

Here you can find some references for the --template syntax.

If you are looking for more flexible formatting that's not supported by template syntax, see config.py.example. You can modify it to your liking and pass as --config to grasp_backend setup command.

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

see todos

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

run ./publish to generate extension zip files
firefox: ./build --firefox --release --lint --sign

After than, upload the signed xpi file on AMO
chrome: ./build --chrome --release --lint

After that, upload the zip (generated by publish script) on Web store

Credits

Icon made by Freepik from www.flaticon.com, licensed by CC 3.0 BY
Original Org Capture extension
Boilerplate for Webpack Chrome extension

grasp's People

Contributors

Stargazers

Watchers

Forkers

lkmokadam powellc mathias alphapapa blueminder alinmear aancel chickensoupwithrice cssm konstantindjairo drjors2 oskarvanderwal wronaq zuoquanxiong infokiller rosstimson

grasp's Issues

Merge captures for the same webpage ?

Hello,

I'm wondering it there would be any way of adding an option to merge captures made for the same website within the same entry.
Knowing the capture template, it could be possible to find if the exact same header is already present in the capture file and then the content could be appended to the already existing entry.

The kind of use-case I'm thinking about with this feature request, is when you are on a page and you want to capture multiple selections, that would then be merged inside a single org header.

Let me know what you think about this !
Thanks in advance for your answer !

Document API for grasp/server

Thanks for Grasp.

It is possible for you to briefly document the API for grasp/server?

I can picture myself hitting it with a range of personal tools other than the browser extension.

Adding support for multiple org files and multiple templates.

Hi, thank you for creating Grasp!

I wanted the ability to choose between multiple org files and multiple templates when capturing, so I added support for that. If you are interested, I can send a pull request. The changes are pretty major though, so I could imagine you rather not want to deal with that.

How it works:
Org files can be configured by creating symlinks in ~/.config/grasp/files to the actual org files. Subdirectories are supported too, which also makes it possible to simply make ~/.config/grasp/files a link to your org directory.

Templates can be configured by placing them in ~/.config/grasp/templates. Files with a .txt extension are treated as simple text templates with the same syntax as the --template parameter. Files with a .py extension should contain a Python class with a method which creates the org text from the supplied data, like the --config parameter (but a bit more general).

Configuring can be done while the server is running, without restarting (when the popup is opened, the extension contacts the server, which sends back the actual content for the popup). The default org-file and default template can be optionally configured by creating appropriate symlinks in ~/.config/grasp. $XDG_CONFIG_HOME is respected. Using the --path, --template and --config parameters still works as expected when ~/.config/grasp/ doesn't exist or doesn't supply the necessary configuration.

Allow escaping of '%' in templates

I'm using vim-zettel to manage my memex and would like to have notes start with '%title [%:description]'

I'm not sure if this breaks the org-mode spec, but having an escape key for % would be useful for my purposes.
I know python but am still figuring out the code base currently, and RE is not my strong suit. Pointers on where to look to add escape characters to the RE parsing would be helpful. Line 66 in org_tools.py seems to be what I need to change?

Currently any text appended to '%' results in an error because it cannot find the variable.

How to install grasp?

I downloaded the zip file and unpacked it.
When I try to start the server, I get an error.
Maybe I need to do something else after unpacking?

$ server/grasp_server.py --path ~/PhpstormProjects/notes/_gtd/grasp_capture.org
  File "server/grasp_server.py", line 44
    globs: Dict[str, Any] = {}
         ^
SyntaxError: invalid syntax

Issue to keep screenshots

Is there a better way?...

Add the ability to create a new file for each note

Hi!
I would like to use deft or notdeft for notes management so that each file matches one note. To add flag in call server/grasp_server.py --multiple-files in command line and to generate a new file while creating every note.

Firefox addon

It seems that there is no firefox addon anymore or link is wrong...

Only capture selection and comments if present

Hello,

First of all, I would like to thank you for this great extension, and for promnesia too !

Regarding this issue, I'm wondering if there would be any way of inserting comments and selections, only if the user added a comment or made one or several selections. By default, the template would only contain a basic template (without comments or/selections entries) defined by the user, and if selection/comments are made they then would be included.
An idea on this side could be to add new options to the server to allow specifying the templates for comments and selections, and only proceed this way if those options are present. I do know that it break a bit the org-capture template definition and feel free to close this issue if you think that this is a behavior you wouldn't want to include.

What do you think about this ?

Newlines being written as '\n'

Hi again. I stumbled across your extension and it pairs very nicely with my newfound interest in org-mode. I wanted to use a custom template so I can get captures similar to Orgzly's format. I passed in the custom template as a command line argument, * %:description \n:PROPERTIES:\n:CREATED: %U\n:END:\n %:link\n %:tags\n %:initial\n but in the file, it shows up as a single line instead of with line breaks.

Experimented with \r\n as I'm on Windows
Works fine when running through a debugger in VSCode
Writes work when I take the formatted template from the debugger and write to the capture file through Python REPL
Issue occurs across all three terminals (Command Prompt, powershell, Windows Terminal)

Environment details:

Python 3.9.0 (tags/v3.9.0:9cf6752, Oct  5 2020, 15:34:40) [MSC v.1927 64 bit (AMD64)] on win32

I'll try reproducing this in a clean environment but for now my workaround is to directly modify the default template in org_tools.py. Any tips for debugging and creating a fix would be great.

Capture multiple selected tabs

It would be very useful for me to capture multiple tabs (or entire window) at once. Combined with tagging would be useful for research purposes.

missing systemd directories during setup

Hello! This is a gift. Thanks for the fantastic web clipping tool!

A small bug:

I didn't have user systemd folders, and the setup script errored out when trying to write ~/.config/systemd/user/grasp.service.

I created the ~/.config/systemd/user/ and then it worked fine.

How to capture the website with my own comments?

I use this package in my Firefox, but it can not capture my comments. My org template is as follows:

python /home/***/nstall/grasp/server/grasp_server.py --path /home/***/org/bookmark.org  --template  $'** [[%:link][%:description]] %:tags\n%U\n' &

How can I capture the website with my witten comments? Thx.

Support selecting multiple ranges

I found one bug though. If I make several text selections on one page, press Ctrl-Alt-Y to capture them, the selections end up concatenated without a newline character.

If it's not too heavy duty, it would make sense to me to create a

#+BEGIN_QUOTE
#+END_QUOTE

block for every selection. I don't think interleaving my comments with selections/quotes is necessary, but I think it makes sense to save selections as quotes.

Can I do this with a different org-mode capture template or does it require changing the extension?

Originally posted by @petr-tik in #7 (comment)

Use xdummy for tests skipped on CI?

From README:

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.

Could xdummy daemon be used to allow running these tests on CI?

Add Markdown support

Hi, would it be possible to convert the selected text to markdown and then capture it? I have (unsuccessfully) tried my hand at it. I tried using the file copy.js from https://github.com/0x6b/copy-selection-as-markdown instead of

code: "window.getSelection().toString();"

in background.js, but the selection variable is always empty.

(I am a js noob)

Markdown support would be really, really great.

Command shortcuts are not configurable in Firefox

Apparently it was broken at some point? Anyway, seems like the fix is there but will only be released in March 2019. So, in the meantime, you can capture via clicking the extension button. I guess I could also just bind something different for Firefox, instead of default Ctrl-Shift-C and Ctrl-Shift-Y, which happen to mean something in Firefox by default.
I'm open for suggestions, since have no idea what common shortcuts are already occupied by the most common Firefox extensions!

Suggestion – unicorn colourful icon options

I have used this extension for years...
But, it is difficult to see the unicorn (black and white) in my icon bar...
Could you add more unicorn colourful icons options for us to select and make a better contrast depending on the firefox/chromium icon bar background?

Thx a lot

Feature: Scroll to ID

I know that this is no longer maintained, but I thought it would be nice if it was possible to check and see if the selected text has an id attribute within it that can be appended to the url. This could be an option that's enabled ("appened id to url"), that way we can click on the urls and be taken directly to where the reference is.

open in sidebar

A feature improvement I could suggest is to open the input area in the sidebar, instead of a pop-up. The pop-up closes when one continues to read the given article. At least for me, this also interrupts the process of thought, I can't reflect on what I have noted already.

I found the side-bar easier for writing and collecting notes, such as in this extension:

https://addons.mozilla.org/en-US/firefox/addon/notes-by-firefox/

Feature idea: quote highlighted text

Just a quick idea that would automate what I’m already doing. I highlight some part of the page I want included in the capture, then copy and paste it into the note. The extension would just have to pull in any selected text to the note input when clicked. This could probably wrap the highlighted/selected text in #+BEGIN_QUOTE / #+END_QUOTE

setup fails when systemd user directory does not exist

When the directory does not exist in user's home directory:

FileNotFoundError: [Errno 2] No such file or directory: '/home/mathiasx/.config/systemd/user/grasp.service'

After creating /home/<username>/.config/systemd/user/ it works. Should the setup script create those directories if they don't exist?

Android extension

Should be fairly easy to implement as a page action for Firefox, I'd imagine similarly easy for Chrome; I just have to figure that out.

Idea: HTTP server in Emacs

Hi,

Somehow I haven't seen Grasp until now. :) I'm curious, have you considered running the HTTP server in Emacs? Then it could add to Org files that are already open in Emacs without worrying about editing conflicts, and it could call Org code like org-id-find.

Add grasp to pypi so it's installable using pip/pipsi

It would be great to be able to install grasp_server as a pypi package to facilitate installing it and including in service scripts for macOS.

Chrome extension loses text when it loses focus

The extension is great! It would be great if it retained the text if it loses focus and clears the text on capture.

I use it to take notes, and frequently it loses focus losing all the text.

Thanks!

Running server/setup fails on macOS

Running Server/Setup fails on macOS with error "FileNotFoundError: [Errno 2] No such file or directory: 'systemctl': 'systemctl'".

This is understandable since macOS does not have systemctl, instead it has launchctl.