How Org Drawers get exported to front-matter.

This feature will work only if the org-hugo-front-matter-format is left at its default value of "toml".

See Org Info: Drawers to learn more about the Org Drawers feature.

:LOGBOOK: Drawer #

Ox-hugo supports parsing of these two kinds of information from the :LOGBOOK: drawers:

  1. TODO state changes saved to these drawers.
  2. Notes saved to the :LOGBOOK: drawers.

The :LOGBOOK: dates and notes exporting features work only if the org-log-note-headings variable is left uncustomized, at its default value.

These features work only if:

  1. org-log-into-drawer (or the :LOG_INTO_DRAWER: subtree property) is set to a non-nil value1, and
  2. Drawer exporting is enabled. You can enable that using #+options: d:t keyword or :EXPORT_OPTIONS: d:t subtree property2.

With :LOG_INTO_DRAWER: enabled, the :LOGBOOK: drawer (default name of this drawer) is created immediately after the Org heading whose state changed or under the heading where the org-add-note command (bound by default to C-c C-z) was called.

Dates parsed from :LOGBOOK: TODO state changes #

This front-matter variable is updated with the timestamp associated with the first TODO state transition to one of the org-done-keywords values3 i.e. transition to DONE state.
This front-matter variable is updated with the timestamp associated with the last TODO state transition to the DONE state, or with the last added note (whichever is the latest).

The date and lastmod values parsed from the :LOGBOOK: drawer state transitions will have the highest precedence. See Front-matter Precedence for more info.

:LOGBOOK: Notes #

  • Notes added to the :LOGBOOK: drawer under the post heading will be exported to the TOML Table Array [[logbook._toplevel.notes]] in the page front-matter.

    Here, _toplevel is a special/reserved TOML Table name to store notes associated with the post’s main heading.

  • Notes added to the :LOGBOOK: drawer under a post’s sub-heading will be exported to the TOML Table Array [[logbook.<sub heading title>.notes]] in the page front-matter.

By design, Ox-hugo exports the :LOGBOOK: drawer notes as data to the front-matter, and user is given the freedom on where and how to render that data.

logbook front-matter Hugo templating examples #

This section shared just one of the ways to render the logbook front-matter data using Hugo templates.

Create layouts/partials/logbook_notes.html in your Hugo site repo with these contents:

{{ with .page.Param .notes_param }}
        {{ range . }}
                <span class="timestamp-wrapper">
                    <span class="timestamp">
                        {{ printf `&lt;%s&gt;` (time.Format "2006-01-02" .timestamp)
                        | safeHTML }}
                {{ .note | $.page.RenderString | emojify }}
        {{ end }}
{{ end }}
Code Snippet 1: logbook_notes.html Hugo Partial

This partial accepts a Hugo dict input argument with keys page and notes_param.

Example of rendering “_toplevel” notes #

Here’s an example of how one could use that partial in the single.html template:

{{ partial "logbook_notes.html"
           (dict "page" $.Page
                 "notes_param" "logbook._toplevel.notes") }}
Code Snippet 2: Example of using logbook_notes.html Hugo Partial in single.html layout file


  • The page key is passed the context of the current page: $.Page.
  • The notes_param key is passed the hierarchical path to the toplevel Logbook notes: "logbook._toplevel.notes".

Example of rendering notes under sub-headings #

Hugo’s Render Hooks for Headings feature can be leveraged for rendering notes entered in :LOGBOOK: drawers under sub-headings in a post.

Create layouts/_default/_markup/render-heading.html in your Hugo site repo with these contents:

<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }}
  <a href="#{{ .Anchor | safeURL }}"><small>#</small></a>
</h{{ .Level }}>
{{ partial "logbook_notes.html"
           (dict "page" $.Page
                 "notes_param" (printf "logbook.%s.notes" .PlainText)) }}
Code Snippet 3: Example of using logbook_notes.html Hugo Partial in render-heading.html

Above, the same logbook_notes.html partial is used but with the notes_param key set differently — This time, it derives the hierarchical path to the logbook. .. .notes TOML Table Array using the Heading Render Hook’s .PlainText variable.

For example, if the sub-heading title is “Example of rendering notes under sub-headings”, the value of .PlainText for that heading will be the same.

  1. See Org Info: Tracking TODO state changes for more information. ↩︎

  2. See the ’d’ option in Org Info: Export Settings↩︎

  3. The default value of the buffer-local variable org-done-keywords in any Org buffer is ("DONE")↩︎

Fork me on GitHub