Replace Front-matter Keys

This is a ox-hugo-unique feature that allows you to replace any front-matter key name to accommodate for your favorite Hugo theme.

The syntax is:

#+hugo_front_matter_key_replace: old_key1>new_key1 old_key2>new_key2

or, if you want this to apply only for a specific Org tree:

:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: old_key1>new_key1 old_key2>new_key2

Here are few use cases to better explain this feature.

Note
I use property drawers in the below examples (used in subtree-based flow). But the same would work for the Org keyword equivalents in file-based flow too.

Use description in Org file, but export as summary #

The Description meta-data is standard in Org and even Hugo. But some theme may choose to have its own front-matter key called summary instead of description.

As summary is not a default front-matter key in Hugo, you would need to set it using the following property:

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :summary "Here is my post summary."

But if you use description, you can use the same in a more concise fashion:

:EXPORT_DESCRIPTION: Here is my post summary.

or even this in the Org body:

#+begin_description
Here is my *post summary*.

And this can be over /multiple lines/ too!
#+end_description

The good news is that you can use the above concise forms (using description) in your Org source, and still export those as summary! 😄

Simply add this at the top of your Org file:

#+hugo_front_matter_key_replace: description>summary

Use Org tags, but export as keywords #

Here’s another scenario.. you painstakingly set Org tags for all your posts, and then you switch to a theme that calls refers to your tags as keywords instead!

Captain HUGO_FRONT_MATTER_KEY_REPLACE is here to help you again! 😎

Just add this at the top of your Org file:

#+hugo_front_matter_key_replace: tags>keywords

Swap tags and categories #

And one more example.. you call them tags, the Hugo theme calls them categories, and vice-versa.

What do you do? ..

#+hugo_front_matter_key_replace: tags>categories categories>tags

Examples #

You can find a bunch of examples if you search for “Replace front-matter keys” in all-posts.org.

  • Those examples are exported as tests tagged replace.
Fork me on GitHub