: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
future self
This post will serve to remind me how to get the :LOGBOOK: notes
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.
As I author my posts in Org mode, I can easy enter a date stamp using
the 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
{{{update(..)}}} Org Macro
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 (\).
:LOGBOOK: #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
needed.
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.
:LOGBOOK: #You need to enable this feature using one of these methods:
org-log-into-drawer variable 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: logdrawer to enable this for the whole Org file.:LOG_INTO_DRAWER: t property 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
subtree’s :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:
:LOGBOOK: note
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:
:LOGBOOK: drawer
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.