Org-mode template expansions for easy code block insertion

emacs
org-mode
code
Creating your own org-mode template expansions
Author

Nicholas Van Horn

Published

April 7, 2014

I have been using Emacs Org-mode (in particular, Org Babel) for reproducible research for several years now. It provides a single, common set of tools for developing and documenting the process of taking a research project from conception to analysis to manuscript writing. And even better, it does so in a language-agnostic manner. This means that rather than juggling Matlab publish reports, R Sweave documents, Mathematica Notebooks, etc. the researcher can unify his/her efforts under a common framework. And I spend most of my time in Emacs anyways, so why not?!

Managing inline code blocks is at the heart of reproducible research in Org-mode. I often write my own expansion templates using yasnippet (there are other options as well, such as skeleton-mode and abbrev-mode) to manage the sometimes confusing array of Babel options. There are a number of options that control whether code, results, or both are exported, and sometimes using template expansions can keep you moving more quickly without error.

Org-mode itself has a completion mechanism built in as well, and I often forget what the expansion keys are. My attempts to google “org mode expansion,” “org babel templates,” etc. usually brings up nothing, and it’s a struggle to remember what these expansion keys are. This post is documentation for me (and for the next googler attempting the same fruitless search) regarding this functionality.

Expansion templates for Org-mode are held in the variable org-structure-template-alist. This is a customizable alist that contains a list of expansion keys, and the values that they expand to. You can inspect this variable by typing C-h v org-structure-template-alist. These expansions work by entering “<” followed by a key of your choice. For example, entering the following at the start of a line:

<s

and executing the completion command (it could be TAB, M-TAB, or C-i) will expand to the following:

#+BEGIN_SRC 

#+END_SRC

If you haven’t customized it, you’re likely to find the following keys: s e q v V c l L h H a A i I, which expand to

<s

#+BEGIN_SRC 

#+END_SRC
<e

#+BEGIN_EXAMPLE

#+END_EXAMPLE
<q

#+BEGIN_QUOTE

#+END_QUOTE
<v

#+BEGIN_VERSE

#+END_VERSE
<V

#+BEGIN_VERBATIM

#+END_VERBATIM
<c

#+BEGIN_CENTER

#+END_CENTER
<l

#+BEGIN_LaTeX

#+END_LaTeX
<L

#+LaTeX:
<h

#+BEGIN_HTML
     
#+END_HTML
<H

#+HTML:
<a

#+BEGIN_ASCII
     
#+END_ASCII
<A

#+ASCII:
<i

#+INDEX:
<I

#+INCLUDE: "/path/to/filename/you/interactively/select"

You can, of course, customize this alist to produce your own expansions. For example, to create a template for producing R code blocks that generate figures to be captured in the export process, we could create the following template expansion:

("r" "#+BEGIN_SRC R :exports both :results graphics :file ./fig_1?.png\n\n#+END_SRC" "<src lang=\"?\">\n\n</src>")

The first string “r” in the list is the expansion key we want to use. The second string contains the text that will replace the expansion key in our text when we expand with TAB later. The third string in the list controls the expansion of our key when Emacs Muse-like expansions are used (I don’t use Muse-like syntax tags in Org-mode, so I haven’t bothered to really customize this.). The question mark “?” in each string controls where point (i.e., the cursor) will be placed after expansion. I have the ? following the file name, as this is something that will need to be different for each code block.

Next, we add our new template to org-structure-template-alist:

(add-to-list 'org-structure-template-alist '("r" "#+BEGIN_SRC R :exports both :results graphics :file ./fig_1?.png\n\n#+END_SRC" "<src lang=\"?\">\n\n</src>"))

You can evaluate the code (move point to just after the final parentheses and enter C-x C-e to create the template expansion. Now we enter our “r” key at the beginning of a line and press TAB, we get:

#+BEGIN_SRC R :exports both :results graphics :file ./fig_1.png
     
#+END_SRC

To make this permanent, we should evaluate our code automatically whenever org is loaded. Putting the following into our init files makes this change permanent:

(eval-after-load 'org
  '(progn
     (add-to-list 'org-structure-template-alist
              '("r" "#+BEGIN_SRC R :exports both :results graphics :file ./fig_1?.png\n\n#+END_SRC" "<src lang=\"?\">\n\n</src>"))))

We can, of course, add any number of these expansion templates.