As an Emacs guy, I attempt to force all my workflow into org-mode – for me life is better in text.

I tend to prefer to store bookmarks in org-mode todo lists, and org-protocol allows external processes to interact with some of org-mode's features. Setup, though, is an hassle. There are plenty of tutorials out there (search), and there are Firefox extensions, but overall I've not had great luck with them.

I therefore decided to put my current setup in this blog post as another data point for those trying to get it all working.

Enable org-protocol:

(require 'org-protocol)

Add a capture template - here's mine:

(setq org-capture-templates
      (quote (...
              ("w" "org-protocol" entry (file "~/org/refile.org")
               "* TODO Review %a\n%U\n%:initial\n" :immediate-finish)
               ...)))

The capture templates section in the org-mode manual will help.

Add the default template to use:

(setq org-protocol-default-template-key "w")

Eval those additions so they're active in your current Emacs session.

Before going further, it's a good idea to test your configuration:

emacsclient -n "org-protocol:///capture?url=http%3a%2f%2fduckduckgo%2ecom&title=DuckDuckGo"

This should pop open a capture window based on the template you added. Until this works, no point in going forward. If it doesn't work, go back through the configuration above and ensure that you've eval'd the code blocks.

If you have an old version of org-mode (older than 7, I believe), the format is different: the urlencoded form is replaced by slashes as separators of the url and title. A quick search will show you the difference.

Now to setup Firefox. Browse to about:config. Right-click on the list of configuration items, choose New -> Boolean, and enter network.protocol-handler.expose.org-protocol for the name and toggle the value to true.

Some tutorials indicate this step is optional – YMMV.

Most of the tutorials include this:

Add ~/.local/share/applications/org-protocol.desktop:

[Desktop Entry]
Name=org-protocol
Exec=/path/to/emacsclient -n %u
Type=Application
Terminal=false
Categories=System;
MimeType=x-scheme-handler/org-protocol;

Then run your updater. For i3 I use (same as for gnome):

update-desktop-database ~/.local/share/applications/

KDE has a different method… again some of the tutorials for getting org-protocol working can help.

Create a bookmark (I create it in the toolbar) with the following "Location":

javascript:location.href="org-protocol:///capture?url="+encodeURIComponent(location.href)+"&title="+encodeURIComponent(document.title||"[untitled page]")

After you save it, should you edit the bookmark, expect to see any spaces replaced by '%20' – the url encoding for a "space".

Now when you click the bookmark, you should get a window opened in an Emacs frame, any random frame, showing your template.

Once you get this all setup, you can start to add more capture mechanisms beyond the "Review {website title}" described above. I have a few others that have been especially helpful:

• I often want to reference the page for research, so this bookmark copies the website title/URL to the org links mechanism. Then you can paste the title/URL as you need. I use this a lot when doing research on the web. Here's the "Location" for the bookmark:

  javascript:location.href='org-protocol://store-link?url='+encodeURIComponent(location.href)+'&title='+encodeURIComponent(document.title)
  

• Bug trackers (Trak and Jira mostly) define much of my workflow, so it's nice when I get assigned a bug to easily create a task from it. There are two parts, as in the "Review" bookmark:

  1. Bookmark

     javascript:location.href="org-protocol:///capture?template=j&url="+encodeURIComponent(location.href)+"&title="+encodeURIComponent(document.title||"[untitled%20page]")
     

  2. Capture Template ("j" for me)

     ("j" "org-protocol-task"
          entry (file+headline "~/org/refile.org" "Tasks")
          "* TODO %a\nSCHEDULED: %t\n%U\n%:initial\n\n"
          :immediate-finish t)
     

• Some websites are valuable and need immediate notes added for context. This bookmark allows you to add your own heading and then a list of keywords to help you find it later.

  1. Bookmark

     javascript:location.href="org-protocol:///capture?template=n&url="+encodeURIComponent(location.href)+"&title="+encodeURIComponent(document.title||"[untitled%20page]")
     

  2. Capture Template ("n" for me)

     ("n" "note"
          entry (file+headline "~/org/refile.org" "Notes")
          "* %^{Title} :NOTE:\n:PROPERTIES:\n:KEYWORDS: %^{Keywords}p\n:END:\n%U\n%a\n\n"
          :clock-in t :clock-resume t :empty-lines 1)
     

If you put them in the toolbar, they're easy to use: