A Scripter's Notes ❚
Emacs, scripting and anything text oriented.

Using Org Logbook Notes to record blog post updates

— Kaushal Modi

Quick introduction to Org mode’s :LOGBOOK: feature and how I use it to record time-stamped notes for blog post updates.

Table of Contents

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.

Prior forms of adding post updates #

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
Code Snippet 1: {{{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 (\).

Introducing :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
Code Snippet 2: Org Drawers

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 :LOGBOOK: #

You need to enable this feature using one of these methods:

  1. Set the 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).
  2. Set #+startup: logdrawer to enable this for the whole Org file.
  3. To enable this feature for only selected subtrees, set the :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:
Code Snippet 3: Default format of a :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:
Code Snippet 4: Examples of post update notes added to the :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.

References #