org-protocol.el – Trigger actions in Emacs via a custom URL scheme

Setup Emacs server

(server-start)
(require 'org-protocol)

Setup the Org protocol scheme handler

• If you use Emacs < 30
  

  Most common desktop environments (Gnome, KDE et al) comply with the XDG Desktop Entry Specification. This means setting up emacsclient as the org-protocol handler using a .desktop file can be regarded as a standard way to set this up in most common desktop environments.

  Some environments, e.g. Gnome as of Gnome 3, have deprecated other configuration methods, e.g. gconftool-2 to set-up protocol handling.

  Create an org-protocol.desktop file either in ~/.local/share/applications/ to set-up emacsclient as the org-protocol handler for the current user or in /usr/share/applications to set-up a system-wide configuration:

  [Desktop Entry]
  Name=org-protocol
  Comment=Intercept calls from emacsclient to trigger custom actions
  Categories=Other;
  Keywords=org-protocol;
  Icon=emacs
  Type=Application
  Exec=emacsclient -- %u
  Terminal=false
  StartupWMClass=Emacs
  MimeType=x-scheme-handler/org-protocol;
  

  Update the cache database of MIME types handled by desktop files via:

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

Test your Org protocol setup

Setup Org protocol capture

Construct Org protocol URL Request

Setup Emacs Server

(setopt server-use-tcp t)
(server-start)
(require 'org-protocol)

Setup the Org protocol scheme handler

Test your Org protocol setup

Setup Org protocol capture

Construct Org protocol URL request

Setup Emacs Server

(setopt server-use-tcp t)
(server-start)
(require 'org-protocol)

Setup the Org protocol scheme handler

REGEDIT4

[HKEY_CLASSES_ROOT\org-protocol]
@="URL:Org Protocol"
"URL Protocol"=""
[HKEY_CLASSES_ROOT\org-protocol\shell]
[HKEY_CLASSES_ROOT\org-protocol\shell\open]
[HKEY_CLASSES_ROOT\org-protocol\shell\open\command]
@="\"C:\\Programme\\Emacs\\emacs\\bin\\emacsclientw.exe\" \"%1\""

Test your Org protocol setup

Setup Org protocol capture

Construct Org protocol URL request

Setup Org protocol capture

org-protocol://capture?template=TEMPLATE&url=URL&title=TITLE&body=BODY

(add-hook 'org-mode-hook
 (lambda ()
   (add-to-list 'org-capture-templates
                ;; The template follows
                '("capture"
                  "Capture (Org Protocol)"
                  entry
                  (file "notes.org")
                  (function (lambda ()
                              (string-join
                               '("* %:description"
                                 ":PROPERTIES:"
                                 ":CREATED: %U"
                                 ":END:"
                                 "%:annotation"
                                 "%i"
                                 ""
                                 "%?")
                               "\n")))
                  :prepend t
                  :empty-lines 1)
                ;; End template
                )))

Setup Org protocol open source

javascript:location.href='org-protocol://open-source://'+encodeURIComponent(location.href)

(setq org-protocol-project-alist
      '(("Worg"
         :base-url "https://orgmode.org/worg/"
         :working-directory "/home/user/worg/"
         :online-suffix ".html"
         :working-suffix ".org")
        ("My local Org-notes"
         :base-url "http://localhost/org/"
         :working-directory "/home/user/org/"
         :online-suffix ".php"
         :working-suffix ".org")))

M-x org-protocol-create-for-org RET

• Handle rewritten URLs
  

  In some cases, replacing :base-url with :working-directory and :online-suffix with :working-suffix will not yield the desired results.

  Suppose you maintain an online store located at http://example.com/. The local sources reside in /home/user/example/. While most of the URLs map directly to local file names by stripping URL parameters from the end and replacing the :base-url with :working-diretory and :online-suffix with :working-suffix, this might not work for rewritten URLs. It's common practice to serve all products in such a store through one file and rewrite URLs that do not match an existing file on the server.

  That way, a request to http://example.com/print/posters-A4.html might be rewritten on the server to something like http://example.com/shop/products.php/posters-A4.html.php, where /posters-A4-digital.html.php is the so called path info. Note that the browser will not notice the rewrite.

  If you now click your org-protocol://open-source:// bookmark, the handler will probably not find a file named /home/user/example/print/posters-A4.html.php and fail.

  Or, even more simple, assume you're browsing http://example.com/. A file named /home/user/example/.php is not likely to exist.

  Since Org-mode commit 69b46e10aab3b2374ecbc1a963ba56e77102a9a4 from 15th Nov. 2009, such an entry in org-protocol-project-alist may hold an additional property :rewrites. This property is a list of cons cells, each of which maps a regular expression to a path relative to the :working-directory.

  Now map the URL to the path /home/user/example/products.php by adding the :rewrites property like this:

  (setq org-protocol-project-alist
        '(("example.com"
           :base-url "http://example.com/"
           :working-directory "/home/user/example/"
           :online-suffix ".php"
           :working-suffix ".php"
           :rewrites (("example.com/print/" . "products.php")
                      ("example.com/$" . "index.php"))
           )))
  

  Guess what the second :rewrites element does. Since example.com/$ is used as a regular expression, it maps http://example.com/, https://example.com, http://www.example.com/ and similar to /home/user/example/index.php.

  The :rewrites are searched as a last resort if and only if no existing file name is matched.

Construct Org protocol URL request

• Web Browser Bookmark
  

  A cross-platform approach to constructing an Org protocol request is to create a web browser bookmark that can run JavaScript as its location.

  1. Create a bookmark in your web browser (Chrome, Firefox, Safari) named "Share Org Link".

  2. Add the following code as the location for this bookmark.

     javascript:location.href='org-protocol://store-link?' + new URLSearchParams({url:location.href, title:document.title});void(0);
     

  3. When visiting a web page, invoke the bookmark "Share Org Link" to share this link to Emacs. Note that a permission may need to be granted with this approach.

  Many different variants of this approach can be taken to cover different Org protocol request types.

• 3rd Party Applications
  
  • Captee (macOS)
    

    Captee is an application that can construct an Org protocol URL from the macOS Share Menu¹. Native apps that support the Share Menu can make an Org protocol store-link or capture request.

  • Acrobat Reader
    

    The guidance in this section is likely stale.

    Adapted from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org

    You place a javascript file for each menu entry in ~/.adobe/Acrobat/<VERSION>/JavaScripts on unix-like systems or c:/Program Files/Adobe/Acrobat <VERSION>/Reader/Javascripts/ on Windows, or wherever your Adobe Reader Installation might look for javascript.

    The examples given here will place new menu entries in the "Tools" menu, after restarting Adobe Reader.

    • org-store-link.js
      

      // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org
      app.addMenuItem({cName:"org-store-link", cParent:"Tools",
         cExec:"app.launchURL('org-protocol://store-link://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title));"});
      

    • org-capture.js
      

      // from https://list.orgmode.org/loom.20080527T012114-502@post.gmane.org
      app.addMenuItem({cName:"org-capture", cParent:"Tools",
         cExec:"app.launchURL('org-protocol://capture://' + encodeURIComponent(this.URL) + '/' + encodeURIComponent(this.info.Title) + '/');"});
      

  • Opera
    

    The guidance in this section is likely stale.

    Opera setup is described here: http://www.opera.com/support/kb/view/535/.

    To set up opera for use with org-protocol, follow these steps:

    1. Choose "Tools" -> "Prefences" from the menu.
    2. Select the tab "Advanced".
    3. Choose "Programs" from the list on the left.
    4. Now click the button "Add" on the very right.
    5. In the new dialog window, enter "org-protocol" as "Protocol", choose the radio button "Open with other application" and enter the path to emacsclient.