notes from /dev/null - scrim

Capturing Org Source Blocks

2025-07-08T17:00:00-07:00

A commonplace activity is to copy source code from a web page into an Org file. Ideally such code is kept structurally intact by wrapping it in an Org source block. This is typically done as follows:

Select source code text in web page.
Copy source code text.
Paste source code into Org file.
Annotate the pasted source code with an Org source block, specifying language. (#+BEGIN_SRC {language}, #+END_SRC)
- Either done manually or using the command org-insert-structure-template (C-c C-,)

While the above is not complicated, it can get onerous if done frequently. Thankfully Org provides you with the means to automate this. For example with Org protocol, the above steps can be reduced to:

Select source code text in web page (no need to copy!).
Run web bookmark to capture selected text to Emacs.
Select source code language via mini-buffer completion in Emacs and commit capture (C-c C-c).

Interested? Read on. Some Elisp ahead, but hopefully not too challenging.

Capturing code with Org protocol

A convenient way to capture content from a web page is through Org protocol which builds on top of Org capture. Some setup is required before using it, but the effort is rewarded in saved time for a future you.

Shown below is a capture template with key name “code”.

("code"
 "Source Code (Org Protocol)"
 entry
 (file "~/org/notes.org")
 (function (lambda ()
             (string-join
              (list "* Source: %:description"
                    ":PROPERTIES:"
                    ":CREATED: %U"
                    ":END:"
                    "%:link"
                    (concat "#+BEGIN_SRC "
                            (cc-org-capture--code-choices "elisp"))
                    "%i"
                    "#+END_SRC"
                    ""
                    "%?")
              "\n")))
 :empty-lines 1)

The Elisp function cc-org-capture--code-choices will generate capture expansion markup to choose a language with mini-buffer completion. It is configured here to use “elisp” as the default language. The set of languages to choose from via completion is defined in cc-org-capture--src-languages. Both their definitions are shown below:

(defun cc-org-capture--code-choices (lang)
  "Create selection of programming language choices with default LANG."
  (concat
   "%^{Language|"
   lang
   "|"
   (string-join cc-org-capture--src-languages "|")
   "}"))

(defvar cc-org-capture--src-languages
  (list
   "C" "F90" "R" "awk" "clojure" "cpp" "css" "ditaa" "dot" "elisp" "eshell"
   "forth" "gnuplot" "haskell" "java" "js" "julia" "kotlin" "latex" "lisp" "lua"
   "makefile" "matlab" "max" "ocaml" "octave" "org" "perl" "plantuml"
   "processing" "python" "ruby" "sass" "scheme" "sed" "shell" "sql" "sqlite"
   "swift" "swiftui" "tcl")
  "List of supported Org capture languages.")

To exercise the capture template named “code” from your JavaScript enabled web-browser, create a bookmark with the following JavaScript code as its location. When you find code you want to capture, select the code and run this bookmark.

javascript:location.href='org-protocol://capture?' +
      new URLSearchParams({
            template: 'code', url: window.location.href,
            title: document.title, body: window.getSelection()});
      void(0);

Aside: if you use Emacs for macOS, you’ll want Scrim to get Org protocol to work.

Capturing source code by copying

Often it is desirable to just copy the source code (putting it in the kill-ring) and paste (or rather capture) it direct into an Org (or Markdown) file of one’s choosing. The following capture template named “cc” can accomplish this.

("cc"
 "Code"
 plain
 (here)
 (function cc-org-capture--code-select-body)
 :empty-lines 1
 :immediate-finish 1)

In the above template, the target (here) is used to insert the captured source code at the current point. The template type is set to plain to not give the captured source code any special treatment with respect to Org structure. The :immediate-finish key is set to non-nil to not create a separate capture window.

The “cc” template is intended to be invoked with a multiple-key sequence starting with ’c’, so the following entry in org-capture-templates is expected.

("c" "Code")

The work of constructing the wrapped source code (in this case, presumed to be in the kill-ring via system copy) is done in cc-org-capture--code-select-body. Its source is shown below.

(defun cc-org-capture--code-select-body ()
  "Body capture code in `kill-ring' head with language prompt."
  (cc-org-capture--code-body-from-kill-ring
   (cc-org-capture--code-choices "elisp")))

(defun cc-org-capture--code-body-from-kill-ring (lang)
  "Generate capture body for LANG code at head of the `kill-ring'."
  (string-join
   (list
    (cc-org-capture--src-block-begin lang)
    (if kill-ring "%c" "")
    (cc-org-capture--src-block-end))
   "\n"))

(defun cc-org-capture--src-block-begin (&optional lang mode)
  "Annotate begin of source code block for given LANG and MODE."
  (let* ((lang (if lang lang "elisp"))
         (mode (if mode mode major-mode)))
    (cond
     ((eq (derived-mode-p mode) 'org-mode) (concat "#+BEGIN_SRC" " " lang))
     ((eq (derived-mode-p mode) 'markdown-mode) (concat "```" lang))
     (t (concat "#+BEGIN_SRC" " " lang)))))

(defun cc-org-capture--src-block-end (&optional mode)
  "Annotate end of source code block for given MODE."
  (let* ((mode (if mode mode major-mode)))
    (cond
     ((eq (derived-mode-p mode) 'org-mode) "#+END_SRC")
     ((eq (derived-mode-p mode) 'markdown-mode) "```")
     (t "#+END_SRC"))))

The implementation of cc-org-capture--code-select-body will check the current major mode (major-mode) and depending if it is Org or Markdown, wrap the copied source code in the kill-ring (expanded by the term “%c”) accordingly.

The following code shows how the “cc” template can be added to org-capture-templates.

(add-hook
 'org-mode-hook
 (lambda ()
   (add-to-list 'org-capture-templates
                '("cc"
                  "Code"
                  plain
                  (here)
                  (function cc-org-capture--code-select-body)
                  :empty-lines 1
                  :immediate-finish 1)
                t)))

If you have C-c c bound to org-capture then you should see the “cc” template in the ’c’ sub-menu.

Caveats

If the source code to be captured contains any text that matches a capture template expansion then it will be processed, likely resulting in unintended behavior. Look out for text that starts with ’%’.

Closing Thoughts

If you’re still here thanks for your attention! This post required a fair amount of Elisp understanding, but the reward for knowing it is the ability to build very bespoke Org capture workflows. Motivated readers are encouraged to take these examples and run with them. To this end I’ve deliberately left out a capture template example of “hard-coding” a language as an exercise to the reader.

If you end up making a template that you think others would find useful, please share it!

Links

If you're on macOS and have Org protocol setup, you might be interested in this post "Capturing an Org note via macOS Shortcuts".

Announcing Scrim - An Org Protocol Proxy for Emacs on macOS

2025-04-28T05:00:00-07:00

Org mode celebrates its ability to export to a multitude of formats. However, lesser known is its ability to import content. One of the ways to import into Org is through a custom URL scheme. This scheme is referred to as Org Protocol (scheme name: org‑protocol://). The motivating idea for using a URL scheme was this: any app outside of Emacs could construct and make an org‑protocol:// URL request without needing any security permissions.

Regrettably, the original implementation of Org Protocol presumed that emacsclient would do the work of making the actual URL request to Emacs. This thinking did not consider the notion that app sandboxing would become widespread practice, preventing other programs from calling emacsclient. So it is with recent releases of macOS: its default policy is to only allow an app to access programs within its prescribed sandbox.

That said, I ❤️ Org Protocol, so much so that I provided support for it in a utility called Captee that lets you share links and text clippings from the macOS Share Menu. I wanted Org Protocol to work on macOS, but for years it was broken due to its dependence on emacsclient. The only workaround was to use the Mitsuharu Yamamoto fork of Emacs which implemented native support for org-protocol:// URL requests. For a number of years, the Yamamoto fork was my daily driver. Unfortunately though, it seems to have succumbed to bit-rot as it has not kept track with recent releases of GNU Emacs (in particular 30.1). I made the switch over to GNU Emacs 30.1, but in doing so I had to give up Org Protocol support.

I missed Org Protocol, so I decided to do something about it. I wrote an app.

Scrim is a macOS utility to act as a proxy to take an Org Protocol request from any app and relay that to Emacs. In effect, Scrim is a native macOS client for Emacs server.

Learn more about Scrim at its website.

Scrim is now available for purchase on the Mac App Store.

As Scrim and Captee compliment each other so well, you can get them both at a discounted price.

Making an App, Looking for Beta Testers

2025-04-14T14:50:00-07:00

Nearly two years back I wrote a utility called Captee that uses the native macOS Share Menu ( ) to share a link or text clipping in either Markdown or Org format. The idea was that any macOS app that supported the Share Menu could take advantage of this. Among the features that Captee supported was the ability to share content via Org Protocol, a custom URL scheme devised to import content into Emacs.

However, for Org Protocol to work, it required that there be a way to transport the org-protocol:// URL request to Emacs on macOS. Org Protocol’s original implementation presumed that emacsclient would do the lifting here, where the sharing app would be able to call emacsclient with the org-protocol// request as its argument. This was however a regrettable design decision made over a decade ago as recent versions of macOS now have a default sandbox policy that prevents an app from calling an executable like emacsclient outside of its sandbox.

The Mitsuharu Yamamoto fork of Emacs got around this restriction by supporting the Org Protocol custom URL scheme natively, where it would directly accept the URL request, bypassing emacsclient. Unfortunately for users of GNU FSF-published Emacs, Org Protocol was viable only if emacsclient was enabled, typically by relaxing macOS security permissions.

To address the above for GNU FSF-published Emacs, I set out to build a proxy utility that would accept the org-protocol:// URL request and transport it to Emacs in a way that conforms to macOS security policies. In effect, I made a macOS client app for Emacs server.

This app is named Scrim and is now in BETA test. I’m looking for testers, especially for those of you who already have Captee. If you’re interested and willing to provide feedback, please add yourself to the Beta test group on TestFlight, an Apple tool for distributing code-signed apps. At current I’m most interested in the following feedback:

Sanity check - Does the app work as advertised?
Were the instructions to setup Emacs server easy to follow? If not, then what was missing?
Are you a user of Captee?

If you do sign yourself up for this, please provide answers to the above via the mail feedback in the Scrim app.

Thanks!

YES, I WANT TO BETA TEST SCRIM