Drawers

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.

These features work only if:

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

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 #

date

This front-matter variable is updated with the timestamp associated with the first TODO state transition to one of the org-done-keywords values³ i.e. transition to DONE state.

lastmod

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).

: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 }}
    <dl>
        {{ range . }}
            <dt>
                <span class="timestamp-wrapper">
                    <span class="timestamp">
                        {{ printf `&lt;%s&gt;` (time.Format "2006-01-02" .timestamp)
                        | safeHTML }}
                    </span>
                </span>
            </dt>
            <dd>
                {{ .note | $.page.RenderString | emojify }}
            </dd>
        {{ end }}
    </dl>
{{ end }}

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") }}

Above,

• 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)) }}

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.