Robin Schwartz

Switching to a Literate Emacs Configuration

Published .

Tags: emacs

Emacs’ org-mode has a number of nifty features. Among them is the ability to sequentially evaluate all the code blocks in an org document with org-babel-load-file.

This makes literate programming extremely easy. Just write a document, intersperse some code blocks, and evaluate. Literate programming has numerous applications: it’s a handy tool for reproducible research, for example.

A number of folks in the Emacs community structure their configuration files as literate programs in org-mode. I’ve been thinking about that for a while, and I finally gave it a shot last weekend. I got some pretty nice results!

How to do it

If you’re interested in rewriting your own configuration as a literate org program, it’s simple:

  • Create a ~/.emacs.d/configuration.org file.
  • Take the contents of your ~/.emacs.d/init.el (or .emacs, if you used that), and move it into that configuration.org file. Wrap it in an emacs-lisp source block, like so:
#+begin_src emacs-lisp
(all-your-config-stuff ...)
#+end_src
  • Replace the contents of your init.el with one line:
(org-babel-load-file "~/.emacs.d/configuration.org")

That’s the first thing Emacs’ll run; it’ll read through that configuration.org file and evaluate that code block.

  • If you restart Emacs everything should still work the way it used to, since the same code is being run. Congratulations: your configuration is now structured as a (really basic) literate program!
  • Break up your configuration into multiple code blocks, structured with headers and useful explanations. This last step may take a while. :-)

Enjoy!