Org mode: tasty tricks

Creating and configuring keywords

One simple, but very powerful feature of Org is that you can define your own set of keywords to use as TODO-states. You can do this on a global level or on the file level. While doing it on the global level might be useful if you always want access to a specific set of keywords, defining your keywords at the file level allows you to work with a custom set of keywords for every file you operate on.

To define keywords for a file, use the #+TODO: keyword and list your desired states, using | as a separator between states that need work and states that that are considered closed. For instance, here's the set of keywords that I'm using for writing this very post. The set indicates whether a heading needs more work, is ready to be reviewed, is done, or if it should be cut:

#+TODO: TODO REVIEW | DONE CUT

Emacs offers you a number of ways to switch the state of an item. By default C-c C-t cycles through the list. You can also use S-<right> and S-<left> (that's S as in super), to change to the previous and next states, respectively.

When you have more than two states, switching to a specific state can start to get tricky if the flow isn't necessarily unidirectional. To make it easier to jump to a state, Org also allows you to add a 'hotkey' that you can use to set that state. This is done by putting the desired key in parentheses after the keyword:

#+TODO: TODO(t) REVIEW(r) | DONE(d) CUT(c)

Now, when you invoke the org-todo command (C-c C-t), rather than cycling through states, Emacs asks you to enter one of the assigned keys. Thus, if an item is currently marked as TODO, but you want to move it to REVIEW, the whole command would be C-c C-t r.

If you want more information assigned to each state, you can also tell Org to log the date and time of when a TODO-state was assigned as well as prompt you to add a note when that happens. As an example, here's the setup I'm experimenting with for recording and tracking blog post ideas:

#+TODO: IDEA(i!) DRAFT(d!) UPDATE(u@) READY(r!) | PUBLISHED(p!) ONHOLD(o@)

The ! after a letter tells Org mode to log the time when this state was entered. The @ tells Org mode that in addition to logging the time, I also want it to prompt me for a little note. With the set above, I want to track the times of all state changes, and when setting the state to UPDATE or ONHOLD, I also want to log a little note. This helps me remember why I put it in that state: Was there a paragraph that needed rephrasing? Have I got a better way to do things that I want to update a post with? Did I no longer see the post as relevant?

The ability to log all of these details is great, but it can quickly get messy. For instance, here's what a heading might end up looking like if we add some timestamps and notes to it:

** CUT Drawers
- State "CUT"        from "REVIEW"     [2020-03-08 Sun 20:17] \\
This is out of scope for now. Consider extracting this into a separate post.
- State "REVIEW"     from "TODO"       [2020-03-08 Sun 20:16]

This can add up fast, so we can make use of what Org calls drawers to keep our file tidy. These are delimited blocks of content that can contain anything but headlines and other drawers. Content put into drawers will be hidden by default (Org collapses it for you), and it will not be expanded by regular visibility cycling. If you want to cycle the visibility of a drawer, place your cursor on the drawer to cycle it.

Logging to a drawer would change the above example to this:

** CUT Drawers
:LOGBOOK:
- State "CUT"        from "REVIEW"     [2020-03-08 Sun 20:17] \\
This is out of scope for now. Consider extracting this into a separate post.
- State "REVIEW"     from "TODO"       [2020-03-08 Sun 20:16]
:END:

Now, no matter how many more entries you add to the log, Org will just show you a collapsed :LOGBOOK: line (that you can expand if you want to). To make Org log into drawers, use the following line:

#+PROPERTY: LOG_INTO_DRAWER t