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

Using Org protocol

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

Using Org protocol

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

Using Org protocol

Test your Org protocol setup

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.

Using Org protocol

• 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.

• Terminal/Shell
  

  Users with shell access can issue the URL request via a command line utility. This utility is platform-dependent.

  On systems supporting XDG, the xdg-open utility can be used.

  On macOS, the open utility can be used.

• 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) + '/');"});