My org mode setup #

This is a description of my org mode setup. I manage most of my life in org mode these days and this is an in-depth write-up of my setup that may interest others.

Introduction #

What is org mode? #

Org mode is an emacs major mode (basically just a set of functionalities to extend the editor) that serves as an outliner and markup language for editing text. This is selling it a little short though, as org mode has so many capabilities and extensions that it is possible to use it for almost anything you can imagine needing or wanting to write in a text editor. I use org files as my environment to take notes, write my journal, write any longer form prose, manage my personal and work task lists, write literate programs and LaTeX documents, write posts for my personal website, and write and publish my digital garden.

org vs. Markdown #

Of course there already exists a lightweight and functional text markup language called Markdown which has become extremely popular in the last ten years as a kind of default format for text. Any text editor or notetaking platform worth its salt among power users will support, or better be entirely built around, Markdown (c.f. Ulysses, Bear, Agenda, iAWriter, Notion). As a markup language in and of itself, org is very similar to Markdown, and I guess suffers from the fact that it is less widely used and maybe has slightly less clean syntax for some common formatting operations. But the fact that it has all sorts of crazy integrations with emacs and other emacs packages is what makes it unquestionably superior to Markdown as a text ecosystem. You’ll see what I mean by that if you make it to the end of this document (which was of course itself written in org).

Productivity #

In fact it sells org very short to refer to it as a markup language or an outliner. Used properly, org mode can form the basis of a bespoke productivity tool that has every feature you’ve ever wanted from any existing tool you care to mention, built exactly how you want it and without any bloat you don’t need. This “build it your way” is core to the emacs experience, at least for people who enjoy it as much as I do, and if you fully embrace this with org mode then the sky is truly the limit for how deep into the rabbit hole you can go making your setup exactly how you want it.

What you’ll see described below in detail is my personal setup, which I have built and rebuilt over the past eighteen months or so (starting in mid 2019) and which I now use to do pretty much everything I do on a computer aside from web browsing. I have written this extensive guide because I know how much I learnt reading about other people’s setups when I was first starting to play with emacs and org mode, and I hope that maybe someone will learn something new from reading mine.

Main setup #

emacs #

You can find my emacs config on this site here or on Github here. I use a fairly simple setup that I built myself. All the packages like Spacemacs and Doom feel a little too constraining for me, and configuring everything from scratch really means you understand how everything works, and helps you learn a little Lisp. Below is a bit more information on the parts of my config that are particularly relevant to my org mode setup.

Font and colors #

I use the great doom themes for emacs, despite not using Doom emacs. There’s loads of fantastic dark and light themes there and you will definitely find one you like. I used the default doom-one for a while, I’m currently trying out doom-vibrant and enjoying it.

I use the Fira Code font everywhere in emacs, including in org documents. There seems to be somewhat of a split in opinion among heavy org mode users on whether to use fixed-width fonts or not; it also looks good with a variable width face but ultimately I prefer the uniform look of a fixed-width face everywhere. On this site I use PT Serif. I guess it depends what aesthetic you’re going for and how much code vs. prose you write.

Finally, I have a series of custom colours that I use for my org headings that I have really grown to like; you are free to steal them if you like:

(custom-set-faces
'(default     ((t (:foreground "#BBC2CF"))))
'(org-level-1 ((t (:foreground "#BF9D7A"))))
'(org-level-2 ((t (:foreground "#E4E9CD"))))
'(org-level-3 ((t (:foreground "#EBF2EA"))))
'(org-level-4 ((t (:foreground "#0ABDA0"))))
'(org-level-5 ((t (:foreground "#80ADD7")))))

Indents and dots #

I see a lot of org mode users using org-bullets, a package that replaces the default asterisks for the different heading depths (analoguous to # in Markdown) with different UTF-8 characters, and also making them different sizes. Something about this just doesn’t sit well with my aesthetic sense so I stay with the default asterisks, although I do hide the leading stars and fix indentation with (org-indent-mode).

File locations #

I keep my files in two folders in my Dropbox, one which is symlinked to ~/org and another which is symlinked to ~/roam.

  • ~/org

    This folder contains all my main org files that are “watched” by Beorg and my agenda.

  • ~/roam

    This folder contains all my notes which are handled with org roam, and a subset of which eventually become this website. See below for details.

Beorg #

Beorg is a really nice native iOS app that handles org files. It has Dropbox sync built in, supports custom agenda views, and is a great way to handle all light usage of org files on the fly. Anything that requires a little more heavy lifting can either wait until I get back to a computer or, if I really have to, use Working Copy (this is a last resort not because of Working Copy, which is fantastic, but just because editing text files on a phone is cumbersome, slow and error-prone). So mostly my mobile usage of org mode is limited to capture and marking tasks as done.

Task properties #

I have tried in the past to give tasks effort estimates (how long I think they will take to complete), but these are pretty useless if you don’t use the powerful clock commands to track time and see if your estimates are even remotely accurate, and this has always felt like a little too much overhead to me. I give tasks related to projects tags so they look a little nicer showing up in the agenda. For tasks at work I use priorities pretty heavily.

Tasks #

I use org mode to manage all the tasks I need to complete throughout the day. Tasks are entered in one of my .org files using the TODO keyword. These tasks can then be populated into an agenda view. I try to use the GTD (Getting Things Done) philosophy, at least in theory, to manage my tasks. It relies on three main ideas.

Capture #

Whenever a new actionable item appears, capture it. Actionable items can be things like

  • tasks: I open the fridge and notice we are out of milk, so add TODO Buy milk to my inbox,
  • notes: I skim an interesting article and want to save it for later or file it, so I add it to my inbox,

or anything else that you want to include in your system. I have a set of personal tasks that mostly relate to administrative items, things around the house, bills and so on, and then another set of “project” tasks for things that I am trying to get done in my various personal projects. I also have an entirely separate file for work tasks.

When I want to capture something I just type C-c c and the capture templates menu appears with my preconfigured task templates (for me it’s just Personal and Work). I can then copy the link, write the task, or note, or whatever, and know that it has disappeared out of my active brain and into my inbox. Importantly, capture can also be done very easily while mobile using the Beorg app.

Review #

It should be very easy to know what to do whenever there is an opportunity to do something. But if you aren’t careful, all those tasks you captured will pile up into your inbox and you will soon be faced with decision paralysis over which task to do next. This is where the “review” process comes in: you need to make it a habit to review and “refile” your inbox tasks into a more actionable list of tasks. The capture phase just guarantees the tasks are somewhere; the review phase now guarantees they are in the right place. For me this just involves incorporating my capture inbox into my agenda and habitually refiling them.

Do #

Of course none of this setup is worth anything if you don’t actually complete tasks. For me the agenda provides a huge motivation for this, having everything I need to do nicely laid out, having recurring tasks pop up when they need to, really removes a lot of cognitive load.

Personal #

Journal #

I use the org-journal package to record my personal thoughts and things that happen in my life every day; I’ve been doing this now for almost three years and it really helps to keep my mind clear and focussed. These journal files are also incorporated into my org roam setup so I have nice backlinks and references.

Administrative and recurring tasks #

org mode has a really great syntax for handling recurring tasks. I use this to handle all sorts of menial things like paying bills, cleaning different things around the house, and my daily habits, which I also use org mode built-in functionality to track. Once everything you need to remember is in a system like this, it begins to feel like a superpower: not only do I never forget these simple but important tasks, but I never even have to think about them at all.

Projects #

Longer-term personal projects are a little trickier, because most of the work here is breaking down a large project like, for example “Create a digital garden website to serve my notes publicly”, into smaller, atomic tasks that can be done in a reasonable chunk of time. This is definitely more art than science.

Agenda #

Personal agenda #

My personal agenda is accessed by typing C-c a a. I press this combination of keys many times a day and the agenda has become my sort of “home page”. It consists of three sections.

  • The main agenda

    This is a list of all the TODO items that are scheduled for today, as well as items with upcoming deadlines, from my main org files in ~/org. When I complete items they get added to a log for the day which gives a really nice sense of completion as the day goes by. I can switch to a week view by pressing w.

  • To refile

    This is a list of all the TODO items in my inbox.org file, i.e. things that I have captured but not put anywhere yet. Whenever I have a few spare minutes I will either refile these items (if they are tasks that need to be done, in which case they should also have a scheduled date or a deadline), or add them to existing notes.

  • People

    This is a list of reminders to get in touch with important people in my life; I generate the TODO s using a Python script and they populate this section.

  • Projects

    I have a number of personal projects which I have broken down into atomic subtasks in my projects.org file. The idea is that each task can be completed in a single session. For each project during my weekly review I make sure I have a single task chosen as the next to be completed; mark it as NEXT instead of TODO, and these all show up as a list at the bottom of my agenda. The idea is that if there is no urgent task in the main agenda, and nothing needs to be refiled from the inbox, then I have free time to work on the next task in some project of my choice.

Work agenda #

I also maintain a separate agenda for all my work projects with a similar structure (there is a separate inbox_work.org file that I capture work-related items into).

Notes #

I have tried many note-taking solutions over the years and eventually settled on using org mode to take all my notes.

Specifically, I use org-roam, a really fantastic extension to org mode that allows you to build a Zettelkasten out of org files. It’s basically a clone of Roam Research, which has been getting a lot of hype lately in the note-taking/productivity world, written for org mode and emacs. I prefer this to using Roam because I can use emacs, customise everything myself, and have control over where my files live. I also have the freedom to build my own web front-end to my notes instead of using the default Roam web application (which I think is extremely ugly).

I move certain things that I capture (articles, papers, text snippets, ideas etc) into a relevant note in the system. I don’t have a nice automatic way to do this yet (setting every single file in my Zettelkasten as an org-refile-target is not really feasible), so I currently move things across manually. This looks like it could partially solve my problem, but because I don’t stick religiously to a heading structure in all my notes, refiling would actually be quite haphazard. Something to think about.

I have over two thousand notes in my Zettelkasten, which contains many thousands of links between files and is slowly becoming a really interesting second brain of sorts. I tag around 20% of it as public and make it accessible at Mt. Solitary, my digital garden. I have a much more detailed writeup of how the publishing process works here.

Literate programming #

Literate programming through org babel is another very nice feature of org mode. It allows you to include, and execute, code snippets from pretty much any language you can think of inside an org file. Think like Jupyter notebooks for Python, but where the encapsulating notebook is written in a highly expressive markup language, and there is support for all programming languages simultaneously.

My most successful foray into this so far has been to rewrite my emacs configuration as an org file, where all the snippets of Lisp that I need are then tangled into my init.el file. I also use it for a few other small Python snippets here and there, and in a few places in my digital garden.

Export #

Finally, one of the most important parts of any plaintext markup language is how rich its export ecosystem is. org mode has so many different export options built-in that I’ve never had to look for something that doesn’t already exist. The nicest documents are those that you export as \(\LaTeX\) files; you can just write straight \(\LaTeX\) into the org file and then when you export it all the equations are properly formatted.

My main use case for this is exporting my public Zettelkasten files to Markdown so they can be served by Hugo; again, see here for more details.

Future #

I am very happy with my setup today. It’s taken me a long time to get something working exactly how I like it and it’s extremely satisfying to have built it myself. So I would like to say that my plans for the future are to do nothing but write, to use the system I built to expand and grow my notes and my personal knowledge base. But of course as anyone who has ever tinkered with this stuff knows, it never ends, and there is always something new that you learn and would like to incorporate into your setup, some cool blog post you read and want to play around with implementing, or just your tastes evolve with time and you feel like it’s time for a change. So I’m not kidding myself: when I think about my projects and the things I spend my free time doing in the future, fiddling with my emacs configuration and building smoother org mode workflows is probably going to be part of it. I just need to learn to be cool with that.