Quick introduction to Org mode’s
:LOGBOOK: feature and how I use it
to record time-stamped notes for blog post updates.
Most of my blog posts are mainly to serve as documentation for my
This post will serve to remind me how to get the
working once again in case I end up with some issue there.
. So when I get a chance, I try to fix outdated stuff in
my old blog posts. And along with the act of updating things, adding
brief notes describing those updates comes naturally to me.
Prior forms of adding post updates #
As I author my posts in Org mode, I can easy enter a date stamp using
org-time-stamp command (bound by default to C-c . RET) and
follow that by the update note.
While that worked, that approach bothered me because those notes
didn’t have consistent format across multiple posts. For example, I
might type the update as “
*Update (<time stamp>)*: <note>” in one post, while I might type the same in a
description list form in another: “
- <time stamp>) :: <note>”.
To solve the consistency problem, I came up with this Org macro:
#+macro: update - $1 :: $2
This worked mostly … except when the update text needed to be a bit
longer, like a paragraph. It didn’t look elegant in that case. Also,
if the text had a comma character in there, it needed to be escaped
with a backslash (
So when I learned
A little bit of history .. I learned about the
:LOGBOOK: drawer when
Adam Porter mentioned it in
ox-hugo Issue # 203 back in
September 2018. I wanted to use that feature, but I didn’t have time
and/or know-how on how exactly I would parse those Org Drawers in
ox-hugo until very recently (May 2022)!
about the Org
:LOGBOOK: drawer, it solved all those problems: (i)
consistency in adding notes (ii) easy to add update notes – in fact
much easier (iii) easy to type long form notes (iv) no comma escaping
Org Drawers look like this:
Content before the drawer :DRAWERNAME: Content inside the drawer :END: Content after the drawer
and they can be inserted anywhere in your Org content using the
org-insert-drawer command (bound by default to C-c C-x d).
:LOGBOOK: is a special kind of drawer that’s auto-inserted by Org
mode when certain actions are detected, like changing the TODO state
of a subtree, or
adding a note . That latter action is what this blog post is about.
Adding notes to
You need to enable this feature using one of these methods:
- Set the
org-log-into-drawervariable to a non-nil value (typically
t) in your Emacs config, or as a file-local variable, or in your project’s
.dir-locals.el(⭐ my preference).
#+startup: logdrawerto enable this for the whole Org file.
- To enable this feature for only selected subtrees, set the
:LOG_INTO_DRAWER: tproperty in the subtree (or one of its parent subtrees).
Once this is set, call the
org-add-note command (bound by default to
C-c C-z). That will open a window with ∗Org Note∗ buffer where-in
you will type your post update and then C-c C-c to save it to the
:LOGBOOK: drawer. If that drawer didn’t exist already, it
will be created directly under the subtree’s heading.
The note will get recorded in this format by default under the current subtree:
* Subtree title :LOGBOOK: - Note taken on <current date and time> \\ <note text> :END:
As you see, you only type the note text, and the time-stamp is inserted automatically.
:LOGBOOK: Notes Example #
Here are the update notes from one of my posts:
:LOGBOOK: - Note taken on <2018-08-26 Sun> \\ Mention =org-babel-demarcate-block=, tweak the =org-meta-return= advice. - Note taken on <2018-08-23 Thu> \\ Use ~M-return~ instead of ~C-return~ for splitting blocks and support upper-case blocks (though I [[* Converting Org keywords to lower-case][don't prefer those]]!). :END:
You can see how they rendered at the top of the Splitting an Org block into two post.
If you are an
ox-hugo user following the subtree-based export
flow, and would like to export
:LOGBOOK: notes in a similar
fashion, check out the
ox-hugo Manual: Drawers page for details.