Merge pull request #504 from kaushalmodi/logbook

Parse `date` and `lastmod` fields from TODO state transitions, and notes from`:LOGBOOK:` drawers
kaushalmodi · May 12, 2022 · 062e88e · 062e88e
2 parents acc91a2 + a356c54
commit 062e88e
Show file tree

Hide file tree

Showing 10 changed files with 642 additions and 124 deletions.
diff --git a/doc/ox-hugo-manual.org b/doc/ox-hugo-manual.org
@@ -862,14 +862,28 @@ set.
 | =tags_weight = 123= (auto-calc)    | =:EXPORT_HUGO_WEIGHT: :tags auto=      | When set to =:FOO auto=, /FOO/ taxonomy weight is auto-calculated          |
 | =weight = 123= (in =[menu.foo]=)   | =:EXPORT_HUGO_MENU: :menu foo=         | Menu weight is auto-calculated unless specified                            |
 |------------------------------------+----------------------------------------+----------------------------------------------------------------------------|
-***** Notes
-- Precedence for =date= parsing :: =CLOSED= subtree property /more
-     than/ =EXPORT_DATE= subtree property /more than/ =#+date:=
-     keyword.
-- Precedence for =draft= parsing :: Org TODO state based /draft/ state
-     /more than/ =EXPORT_HUGO_DRAFT= subtree property.
-- Custom front-matter parameters :: See the [[*Custom Front-matter Parameters][Custom Front-matter
-  Parameters]] section.
+Also see the [[*Custom Front-matter Parameters][Custom Front-matter Parameters]] section.
+***** Front-matter Precedence
+:PROPERTIES:
+:CUSTOM_ID: front-matter-precedence
+:END:
+- Precedence for =date= parsing ::
+  1. First transition to a /DONE/ state recorded in =:LOGBOOK:= (see
+     {{{titleref(Drawers#logbook-dates,Dates parsed from ~:LOGBOOK:~
+     drawers)}}})
+  2. =CLOSED= subtree property
+  3. =EXPORT_DATE= subtree property
+  4. =#+date:= keyword
+- Precedence for =lastmod= parsing ::
+  1. Last (second or later) transition to a /DONE/ state recorded in
+     =:LOGBOOK:= (see {{{titleref(Drawers#logbook-dates,Dates parsed
+     from ~:LOGBOOK:~ drawers)}}})
+  2. =lastmod= set automatically if =:EXPORT_HUGO_AUTO_SET_LASTMOD: t=
+     *and* if it's not derived from the =:LOGBOOK:= drawer.
+  3. =EXPORT_HUGO_LASTMOD= subtree property or =#+hugo_lastmod:= keyword
+- Precedence for =draft= parsing ::
+  1. Org TODO state based /draft/ state
+  2. =EXPORT_HUGO_DRAFT= subtree property
 **** For file-based exports
 #+caption: Hugo front-matter translation for file-based exports
 #+attr_html: :class sane-table
@@ -1079,6 +1093,11 @@ It's normal for one to choose to auto-set the /last modified/ date for
 all the posts. So instead of setting the above property for each post
 individually, it might be more convenient to simply put
 =#+hugo_auto_set_lastmod: t= at the top of the file.
+
+But note that if the =lastmod= date is parsed from the
+{{{titleref(Drawers#logbook-dates,~:LOGBOOK:~ drawer)}}} that value
+will take precedence, and the "auto set lastmod" feature will be
+disabled.
 *** Image Links
 :PROPERTIES:
 :EXPORT_FILE_NAME: image-links
@@ -4345,6 +4364,150 @@ This feature has language support too. If the ~#+language~ keyword is
 set to a language code other than ~en~ (example: ~de~), the
 translations of the element type names get exported. The translations
 are based on the ~org-export-dictionary~ variable from ~ox.el~.
+*** Drawers
+:PROPERTIES:
+:EXPORT_FILE_NAME: drawers
+:END:
+#+begin_description
+How Org Drawers get exported to front-matter.
+#+end_description
+#+begin_note
+This feature will work only if the ~org-hugo-front-matter-format~ is
+left at its default value of ~"toml"~.
+#+end_note
+See [[info:org#Drawers]] to learn more about the Org Drawers feature.
+**** ~:LOGBOOK:~ Drawer
+:PROPERTIES:
+:CUSTOM_ID: logbook-drawer
+:END:
+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.
+
+#+begin_note
+The ~:LOGBOOK:~ dates and notes exporting features work only if the
+~org-log-note-headings~ variable is left uncustomized, at its default
+value.
+#+end_note
+
+These features work only if:
+1. ~org-log-into-drawer~ (or the ~:LOG_INTO_DRAWER:~ subtree property)
+   is set to a non-nil value[fn:13], *and*
+2. Drawer exporting is enabled. You can enable that using ~#+options:
+   d:t~ keyword or ~:EXPORT_OPTIONS: d:t~ subtree property[fn:14].
+
+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
+:PROPERTIES:
+:CUSTOM_ID: logbook-dates
+:END:
+- ~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[fn:15] 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.
+
+  Note that if only one transition to the /DONE/ state was recorded,
+  then this front-matter variable remains unset.
+
+#+begin_note
+The ~date~ and ~lastmod~ values parsed from the ~:LOGBOOK:~ drawer
+state transitions will have the highest precedence. See
+{{{titleref(Org meta-data to Hugo
+front-matter#front-matter-precedence,Front-matter Precedence)}}} for
+more info.
+#+end_note
+***** ~: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:
+
+#+name: code__logbook_notes_partial
+#+caption: ~logbook_notes.html~ Hugo Partial
+#+begin_src go-html-template
+{{ 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 }}
+#+end_src
+
+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:
+#+name: code__rendering_toplevel_logbook_notes
+#+caption: Example of using ~logbook_notes.html~ Hugo Partial in ~single.html~ layout file
+#+begin_src go-html-template
+{{ partial "logbook_notes.html"
+           (dict "page" $.Page
+                 "notes_param" "logbook._toplevel.notes") }}
+#+end_src
+
+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 [[https://gohugo.io/templates/render-hooks/#heading-link-example][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:
+#+name: code__rendering_sub_heading_logbook_notes
+#+caption: Example of using ~logbook_notes.html~ Hugo Partial in ~render-heading.html~
+#+begin_src go-html-template
+<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)) }}
+#+end_src
+
+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.
 ** Meta
 :PROPERTIES:
 :EXPORT_HUGO_MENU: :menu "7.meta"
@@ -4713,8 +4876,13 @@ Categories,)}}}.
   maintaining global variables.
 * Footnotes
 
+[fn:15] The default value of the buffer-local variable
+~org-done-keywords~ in any Org buffer is ~("DONE")~.
 
+[fn:14] See the *'d'* option in [[info:org#Export Settings]].
 
+[fn:13] See [[info:org#Tracking TODO state changes]] for more
+information.
 
 [fn:3] The ~dvisvgm~ and ~dvipng~ executables ship with TexLive
 distributions.