Allow exporting any Org Special Block to a front-matter variable

[kaushalmodi]

Idea by @pdcawley

It's literally a matter of having a front-matter-special-blocks-alist, initially containing '(("description" . :description))' and rejigging the first clause of the main cond to look at the alist rather than using the hardcoded "description" stuff.

Example snippet by his tweet:

(defvar org-hugo-special-block-type-alist '(("description" . :description)))
…
(when contents
  (cond
   ((if-let ((match (assoc block-type org-hugo-special-block-type-alist)))
(plist-put info (cdr match) contents))
    nil)
…))

[kaushalmodi]

We already have org-hugo-special-block-type-properties. May be introduce a new property to the plist called :front-matter.

User config will then look like:

(with-eval-after-load 'ox-hugo
  (add-to-list 'org-hugo-special-block-type-properties '("announcement" . (:front-matter "announcement"))))

[kaushalmodi]

Specification

Variable

• New key :front-matter in org-hugo-special-block-type-properties

Example

(with-eval-after-load 'ox-hugo
  (add-to-list 'org-hugo-special-block-type-properties '("announcement" . (:front-matter "announcement"))))

Usage

• Valid usage: The Org special block associated with a front-matter parameter can appear at most once in a post.
  • Example based on the above "announcement" special block:

    #+begin_announcement
    something 1
    #+end_announcement
    

• Error condition: If second special block of the same type is seen, throw a user-error.
  • Error example based on the above "announcement" special block. The special block appears twice in the post.

    #+begin_announcement
    something 1
    #+end_announcement
    something 2
    #+begin_announcement
    something 3
    #+end_announcement    
    

Set this using Org keywords as well?

Generally a user will have a fixed set of special blocks that they would want to convert to front-matter. So they would set org-hugo-special-block-type-properties in their Emacs config.

Is there a reason to support setting the "special block -> front-matter" association using Org keywords?

[pdcawley]

Is there a reason to support setting the "special block -> front-matter" association using Org keywords?

At present, I build bofh.org.uk in a Github Action that works by grabbing emacs and ox-hugo and calling emacs ./org-content/all-posts.org --batch -q -L ~/ox-hugo -l ox-hugo.el --eval='(progn (setq org-confirm-babel-evaluate nil) (org-hugo-export-wim-to-md t))' --kill. This isn't touching any startup files, so the only place it can pick up that extra configuration, at present, is from the org-file itself, so some means of specifying that

#+begin_twitter_announcement
Hey, I posted something new and fascinating on my blog, check it out!
#+end_twitter_announcement

needs to go into the announcement metadata. I can always add a fragment of elisp to the repo to setup such stuff, but that strikes me as inelegant.

[pdcawley]

Actually, so long as the special blocks alist is marked as safe to be made buffer local, I can get away with:

# -*- mode: org; org-hugo-special-block-type-properties: (("announcement" :front-matter "announcement")); ...; -*-

Or I could hoist it to a .dir-locals.el file, come to that.

[kaushalmodi]

@pdcawley Kind of related .. ox-hugo now supports parsing LOGBOOK drawer notes to front-matter. See https://github.com/kaushalmodi/ox-hugo/pull/504 for examples, documentation and code if you are interested.

After that PR, I wonder, if using Org Special Blocks is the right thing for front-matter generation. Have you considered using Org Drawers for that instead (https://orgmode.org/manual/Drawers.html) ? I can add support for arbitrary drawer -> front-matter conversion in a similar vein of what I did for the LOGBOOK drawers.

One of my reasons is .. if the Org Special Blocks are getting too much overloaded at this point.. You can already see the different ways in which ox-hugo is using Org Special Blocks at the moment: https://ox-hugo.scripter.co/doc/org-special-blocks/. On the other hand, the Org Drawers are severely under-utilized.

Thoughts??

[pdcawley]

I'm not particularly attached to the mechanism by which something is hoisted to the .md file's front matter, I just want to avoid having to mess with :export_hugo_custom_front_matter: if I can possibly help it because it's not a format I find remotely nice to have to deal with, especially for chunks of text that should ideally be converted to markdown (or html) on their way to the front matter. If Org Drawers are a route to doing that, then I'm all for them.

[kaushalmodi]

If Org Drawers are a route to doing that, then I'm all for them.

Awesome!

Just to note, the contents of the drawers will hide by default until you hit TAB on the drawer header. But once expanded, you can edit content in there as you would normally in Org.