This is an extension for Google Chrome (tm) and Firefox (tm) which adds a "Capture" button, sending the site address, title, and selected text (if any) to emacs via org-protocol, see the Org-Mode site for instructions for setting that up org-protocol. The extentsion itself is available at the Chrome App Store.
- Adding options for selecting the exact structure of the links that are constructed (e.g. for the benefit of people with '///' problems).
- There is always room to improve. Open a ticket with your ideas.
Problems? Please click here or scroll to the bottom.
Either via the Chrome App Store or by dragging the extension folder to the "Extensions" tab in Chrome. If the latter is the chosen procedure then one needs to enable developer mode first, if I'm not mistaken. Note that if you choose to have a local-install, then you need to choose some icon and name it org-mode-unicorn.png, placing it in the extension's folder. Or, you can name it anything you want, but then you need to update manifest.json.
Note: The first time you use the extension, Chrome will ask you allow it to run open .... (on OSX) or xdg-open ... (on Linux), or ??? (On Windows). Those are the standard system mechanisms for dispatching a file/URL to the appropriate handler, so you should accept the request.
Detailed instructions available at Org-Mode site.
The gist of it is to make your system recognize emacsclient as the handler of org-protocol:// links. In addition, one needs to set up emacs to load org-protocol and to set up capture templates.
cat > "${HOME}/.local/share/applications/org-protocol.desktop" << EOF
[Desktop Entry]
Name=org-protocol
Exec=emacsclient %u
Type=Application
Terminal=false
Categories=System;
MimeType=x-scheme-handler/org-protocol;
EOFAnd then, for GTK-based DE:
update-desktop-database ~/.local/share/applications/For KDE5:
kbuildsycoca5
xdg-mime default org-protocol.desktop x-scheme-handler/org-protocolNote: This is a workaround to issue #16 - See comment here
Create the file /usr/local/bin/emacs-capture
#!/bin/bash
# HACK: workaround for a kde-open bug (feature?) that might have
# eaten a colon from our argument, om nom nom
argv=()
for arg in "$@"; do
re='s_^org-protocol:/+capture:?/+_org-protocol://capture://_'
argv+=("$(echo -n "$arg" | sed -Ez "$re")")
done
# Note: feel free to add any other arguments you want,
# e.g. emacsclient --alternate-editor= -c "${argv[@]}"
emacsclient "${argv[@]}"And the file
$HOME/.local/share/applications/emacs-capture.desktop
#!/usr/bin/env xdg-open
[Desktop Entry]
Name=Emacs Client
Exec=emacs-capture "%u"
Icon=emacs-icon
Type=Application
Terminal=false
MimeType=x-scheme-handler/org-protocol;Finally, run
kbuildsycoca4
sudo update-desktop-databaseStart Applescript Editor. Paste the following snippet:
on emacsclient(input)
do shell script "/Applications/Emacs.app/Contents/MacOS/bin-x86_64-10_9/emacsclient -n -c -a \"/Applications/Emacs.app/Contents/MacOS/Emacs\" '" & input & "'"
end emacsclient
on open location input
emacsclient(input)
end open location
on open inputs
repeat with raw_input in inputs
set input to POSIX path of raw_input
emacsclient(input)
end repeat
end open
on run
do shell script emacsclient("")
end runAdjust the paths and save it (with 'type' as Application) under /Applications/EmacsClient.app (or whatever else you choose).
Edit (with Xcode) the file /Applications/Emacsclient.app/Contents/Info.plist
And add there the following:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string>org-protocol</string>
<key>CFBundleURLSchemes</key>
<array>
<string>org-protocol</string>
</array>
</dict>
</array>and
<key>CFBundleDocumentTypes</key>
<array>
<dict>
<key>CFBundleTypeExtensions</key>
<array>
<string>*</string>
</array>
<key>CFBundleTypeName</key>
<string>All</string>
<key>CFBundleTypeOSTypes</key>
<array>
<string>****</string>
</array>
<key>CFBundleTypeRole</key>
<string>Viewer</string>
</dict>
</array>and restart the desktop. You can also download EmacsClient.app.zip, which I prepared in advance, if you are lazy.
If you have Homebrew and Homebrew-Cask installed, you can also install EmacsClient.app.zip with brew cask install emacsclient
Under some setups the emacs frame does not appear on top. @dangom proposes a workaround using hammerspoon:
Add the following to your init.lua:
function emacsclientWatcher(appName, eventType, appObject)
if (eventType == hs.application.watcher.activated) then
if (appName == "Emacsclient") then
-- Bring Emacs to Front
hs.osascript.applescript('tell application "Emacs" to activate')
end
end
end
appWatcher = hs.application.watcher.new(emacsclientWatcher)
appWatcher:start()Open the Registry Editor (Win-R, then type regedit). Within HKEY_CLASSES_ROOT, add a key called org-protocol. Within org-protocol, set the data for the string value with the name (Default) to be URL:org-protocol, add another string value with name URL Protocol and no data, and add a key called shell.
Within shell, create a key called open.
Within open, create a key called command.
Within command, set the data for the string value with the name (Default) to "C:\the\path\to\your\emacsclientw.exe" "%1", updating the path to point to your Emacs installation.
If you get stuck, see this guide to registering a protocol handler and look at how registries are set up for other protocol handlers (skype, ftp, etc.). Most of your pre-existing protocol handlers have more config than you need.
If some text is selected before the button is clicked, then the following is sent to emacs:
org-protocol://capture:/p/<url>/<title>/selection>
If nothing is selected, then instead the following is sent:
org-protocol://capture:/L/<url>/<title>
This means that you need to have appropriate capture templates for "L" and for "p". Example templates below:
(setq org-capture-templates `(
("p" "Protocol" entry (file+headline ,(concat org-directory "notes.org") "Inbox")
"* %^{Title}\nSource: %u, %c\n #+BEGIN_QUOTE\n%i\n#+END_QUOTE\n\n\n%?")
("L" "Protocol Link" entry (file+headline ,(concat org-directory "notes.org") "Inbox")
"* %? [[%:link][%:description]] \nCaptured On: %U")
))Hint: You can put code in capture handlers via %() blocks. I use this mechanism to automatically close the newly crated frame in the L template. If anyone cares to know, I'll add the details. Another example use is below.
Note: The L template above would break for links to pages having [ and ] characters in their page titles - notably ArXiv. To mitigae this, you can use the improved template, contributed by Vincent Picaud:
(defun transform-square-brackets-to-round-ones(string-to-transform)
"Transforms [ into ( and ] into ), other chars left unchanged."
(concat
(mapcar #'(lambda (c) (if (equal c ?[) ?\( (if (equal c ?]) ?\) c))) string-to-transform))
)
(setq org-capture-templates `(
("p" "Protocol" entry (file+headline ,(concat org-directory "notes.org") "Inbox")
"* %^{Title}\nSource: %u, %c\n #+BEGIN_QUOTE\n%i\n#+END_QUOTE\n\n\n%?")
("L" "Protocol Link" entry (file+headline ,(concat org-directory "notes.org") "Inbox")
"* %? [[%:link][%(transform-square-brackets-to-round-ones \"%:description\")]]\n")
))If you wish to automatically close the emacs frame after a capture, add the following template:
("L" "Protocol Link" entry (file+headline ,(concat org-directory "notes.org") "Inbox")
"* %? [[%:link][%:description]] %(progn (setq kk/delete-frame-after-capture 2) \"\")\nCaptured On: %U"
:empty-lines 1)and in the initialization of org-mode put:
;; Kill the frame if one was created for the capture
(defvar kk/delete-frame-after-capture 0 "Whether to delete the last frame after the current capture")
(defun kk/delete-frame-if-neccessary (&rest r)
(cond
((= kk/delete-frame-after-capture 0) nil)
((> kk/delete-frame-after-capture 1)
(setq kk/delete-frame-after-capture (- kk/delete-frame-after-capture 1)))
(t
(setq kk/delete-frame-after-capture 0)
(delete-frame))))
(advice-add 'org-capture-finalize :after 'kk/delete-frame-if-neccessary)
(advice-add 'org-capture-kill :after 'kk/delete-frame-if-neccessary)
(advice-add 'org-capture-refile :after 'kk/delete-frame-if-neccessary)Is the extension not working as you expect? i.e., is it "broken"? You need to do some investigative legwork. And if you open a ticket, provide enough information to help solve the problem!
Please describe your setup. Linux? Version. OSX? Version. Emacs? Version. org-mode? Version. Chrome? Version. How did you get your system to send org-protocol links to emacs? Please provide the relevant capture templates.
Please find the simplest URL for which it fails (does it work on a simple address that contain only alphanumeric characters and periods? and backslashes? and query parameters? and escaped characters? etc.). Then open the developer console and look for the debug message that the extension gives and add it to the ticket.
Open a terminal and run $open "COPIED-URL" (do not skip the quotes, unless what you are pasting already has quotes around it). $open is simply open if you are on OSX and xdg-open if on linux. COPIED-URL is obviously the url you pasted here in step 1. Does it work? Congrats, you found where the problem is not (i.e. inside chrome). No? Does $open org-"protocol://capture:/p/a/b" work? No? Again you found where the problem lies not. Otherwise proceed to step 3.
Call up the line you ran in the terminal with the non-working url. it will be of the form open "org-protocol://capture://PIECE1/PIECE2/ with PIECE2 usually being longer and more complex if you selected any text, and PIECE1 otherwise. Please edit the url until it is as short as possible while still breaking (Note, % should always be proceeded by two digits/letters in the ranges 0-9 and A-F so do not leave a percent sign with a single symbol following). You can probably trim one of the pieces to be just one character. Add to the ticket the smallest breaking URL.
Try sending said URL directly to emacsclient, for good measure. Does it work? Again, congrats. If you are using OSX, make sure that the emacsclient which you call is the correct one!
It is of course fine to ask for help with problems in your config as well.
This repository is licensed as MIT license, see the LICENSE file for details.