Notes on Emacs Org mode

As part of my quest to master Emacs, which is sort of a sub-quest on the way toward learning more about Lisp, I have spent a fair amount of time discovering various corners of the Emacs world. One of those is the famous "Org mode" that is used for a wide variety of organizational tasks within the editor—and not just Emacs, but for Vim and others too. Org mode can be used for to-do lists, notes with interconnections between them, literate programming, web sites, and more. Now my quests are growing quests of their own and digging into Org mode is one of those.

It is hard to visit the land of Emacs without encountering multiple glowing accounts of using Org mode for all manner of different tasks. I had been exposed to it a bit over the years via a look at Beancount, the text-based accounting system that accommodates Org markup, by its mention in a discussion of making Emacs more popular in 2020, and in editing an article about to-do list management later that year. Until recently, though, I had not really dipped my own toes in Org.

Org start

As with many other things, especially with regard to Emacs, coming up to speed on Org is no simple task—the fundamentals are straightforward, but there is so much more depth (and width) to the topic. The main idea behind Org is to be a text-markup language, similar in formatting scope and age to Markdown, but different—Org goes beyond just simple formatting for one thing. The intent is to produce something that humans and programs can read easily—the latter can then transform the text into multiple different kinds of output. Org can be exported into almost a dozen different formats "out of the box", including HTML, LaTeX, Markdown, Texinfo, and OpenDocument text. Naturally, new back-ends can be added to support additional export options.

The simple formatting pieces are various levels of "headlines" that are indicated using asterisks, lists of various sorts using a handful of different punctuation marks to indicate each entry, and punctuation for styling words and phrases (e.g. italics and bold). The Org-mode quick start page has a fast-paced overview of the different kinds of markup, beyond headlines, lists, and style attributes; it adds links, images, tables, and more. An example Org file might look something like the following:

    * My first Org file
    
      ** Org has different levels of headlines
      
      ** Lists in Org can take several different forms
      
         *** For example:
             - this is a simple list
             - with two entries
             
         *** While this is a numbered list with sublists
             1. Entry one
                + has a sub-list of three entries
                + second
                + third
             2. El segundo
                - yet another
                - list type
                
      ** Meanwhile, we can add style attributes
         - *bold*
         - /italic/
         - _underlined_
         - and more

The first thing to realize, though, is that the file may look more or less that way in the Emacs buffer, due to Org mode (and, more importantly, Org Indent minor mode), the actual text in the file on disk is (mostly) flush-left. On my system, Org mode was enabled by default for .org files, but Org Indent needed to be enabled via M-x customize or the startup file. In my Emacs buffer, the headline stars are condensed to a single star and the different levels are color-coded and indented; in addition, the style attributes are reflected on that text in the buffer, so "*bold*" is in bold, for example.

Working with multi-level lists is a bit fiddly in my (limited) experience so far. Watching a screencast recommended by the "Org mode beginning at the basics" tutorial was instructive, though I generally prefer textual over video-based information, perhaps unsurprisingly. There are various things that can be done with lists using just a few keystrokes, such as reordering entries, changing the type of list, hiding and revealing sub-entries, adding checkboxes that can be toggled for entries, and more.

Beyond that, the different headline levels can be collapsed or exposed by using the tab key (shift-tab too, of course). That allows a larger Org document to be reduced to just the top-level headlines, for example, only exposing the particular area being worked on.

To do

The management of to-do lists is one of the most-mentioned uses for Org mode and, as with much of the rest of it, there are some simple basics along with plenty of depth for those who want more. Any headline or list element can be marked with "TODO" to turn it into a TODO item; "TODO" displays in red on my system, though that can undoubtedly be configured. Typing shift-right-arrow anywhere in the item turns that into "DONE" (in green), doing it again removes any text there, and once more goes back to "TODO". That means any entry can be turned into a TODO item with a single keystroke; the left-arrow counterpart goes backward through the sequence as might be expected.

TODO items can be highlighted in a file with a key sequence; that will collapse all of the entries that are not labeled "TODO". You can also add files with TODO items to an "agenda" and there are keystrokes to gather all of the items from those files into one buffer or file to assemble an agenda. There are, inevitably, many different kinds of customization that can be done, starting with the different states (TODO, DONE) that an item can be placed in. Based on the amount of (virtual) ink (and video pixels) expended on it, Org mode is clearly one of the most-used features of Emacs—just after editing text, presumably.

Some of that virtual ink is what caught my eye and set me on course to look more deeply at Org. Eric MacAdie had a new-year's blog post on Org commands that I noticed in an issue of Sacha Chua's (incredibly detailed) "Emacs news" the other day. MacAdie has had other Emacs-related blog posts that I found interesting along the way; there is quite a backlog of stuff to read there.

He apparently has a general aversion to Emacs key sequences (and "chords"), but it is pretty easy to convert the M-x commands he talks about to their key shortcuts. He pointed to a Udemy course from Rainer König on using Org mode; once I realized it came with a 100-page PDF text, I paid the (small) fee and figured I could skip the videos. In the end, I have watched some (and will likely watch more); the presentation is somewhat bland, perhaps, but definitely useful. The tool König uses to highlight his keystrokes in Emacs is quite helpful, as it is difficult to see them in screencasts and the like.

Babel

I had already started taking some notes (for a related article that may appear here one day) in an Org mode file before being reminded about the TODO features via MacAdie's post. In those notes, I had started playing around with executing code directly from within an Org file, which is somewhat similar to the functioning of computational notebooks for Python, Julia, and other languages (e.g. IPython and Pluto). Org mode has a built-in extension, Babel, that allows placing code directly into text files, executing it, and incorporating the output into the text.

Babel can be used in various ways. The "Introducing Babel" page describes one way it could be used:

A piece of data might pass from an Org table to a Python code block, then maybe move on to an R code block, and finally end up embedded as a value in the middle of a paragraph or possibly pass through a Gnuplot code block and end up as a plot embedded in the document.

It provides a way to do literate programming in Emacs using text files. Or to simply ensure that one's examples in, say, an article or book, actually do what is expected. There are various Babel back-ends for different programming languages, which can all be mixed as described.

There is a long list of languages that are shipped with Emacs, though they need to be activated before they can be used in Babel. There are also some lesser-known languages distributed in org-contrib; even more can be found in the Emacs Lisp Package Archive (ELPA) and elsewhere. The configuration of some languages (e.g. Racket for Org Babel) looks to be a little tricky, perhaps, though I was able to do some preliminary testing with both Common Lisp and Python—Racket will have to wait.

Roam (if you want to)

Another Org tool that has caught my eye recently is Org-roam, which I have not tried at all, but it looks intriguing (always dangerous). It allows one to create a Hypercard-like network of notes files that is sometimes referred to as "your second brain"—or words to that effect. I stumbled into it via a web search for "note taking in org mode" or similar, which landed me on two different blog posts (first, second) that talk about creating, maintaining, and using a "note network" with Roam.

So, I should add Roam to the ever-growing list of "things I should look more closely at", and I would, if only I had a way to Organize such a list. Bad jokes aside, that is a real danger when you (or at least I) start down a path of this nature: the amount of subject matter simply explodes in an almost combinatorial way. It can be difficult to get far enough along with one topic or area before getting distracted into another. But so it goes—learning new things is always fun—and life is truly not about the destination, after all.

In the six or so months of my journey trying to do more with Emacs than just the bare minimum needed to get my job done, I have learned a lot. I am starting to get a real feel for the advantages of having "everything" available within a single environment, with a mostly consistent, if idiosyncratic, memory-taxing, and finger-twisting, set of commands. Those advantages have always been touted by Emacs advocates, of course, so I was not unaware of their existence. Personally, I never saw a need for that all-encompassing experience, but maybe I should have gone down this rabbit hole long ago. Now I start to wonder if I should be considering email in Emacs—the rabbit holes abound.

This concludes a highly personalized look—something of whirlwind brain dump, perhaps—at Org mode. It hopefully gives a bit of a taste for what it can do in Emacs, but there is at least some support for its features in other editors, so those users (including me) can still take advantage. Readers who want more information about Org will find plenty of starting points in the article, but there is one more to add to the list (perhaps a list in a .org file): Worg, the "World of Org" community wiki. Readers can rest assured that there is ample width, depth, and a couple of other dimensions thrown in for texture in Org mode—and Emacs, itself, of course.