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: oldkey1>newkey1 oldkey2>newkey2

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

:EXPORT_HUGO_FRONT_MATTER_KEY_REPLACE: oldkey1>newkey1 oldkey2>newkey2

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.

1 Use description in Org file, but export as summary #

The Description meta-data is standard in Org.

Starting with v0.55.0, Hugo now supports summary as a built-in front-matter variable to directly specify the post summary. See Hugo commit 3a62d547 for details.

As the summary parameter does not have explicit support in ox-hugo, you would need to set it using the following property:

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

But instead, you can simply add this at the top of your Org file:

#+hugo_front_matter_key_replace: description>summary

and then use description to do the same:

:EXPORT_DESCRIPTION: Here is my post summary.

It gets even better if you use the description Org Special Block :

#+begin_description
Here is my *post summary*.

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

By doing above, you would be using description in your Org source, but that would get exported as summary in the Markdown! 😄

2 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

3 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

4 Removing front-matter keys during export #

In the front-matter key replacement syntax:

#+hugo_front_matter_key_replace: oldkey>newkey

If newkey is a special string nil, oldkey will be removed from the exported front-matter.

For example, if you want to remove the aliases front-matter from your exported files (but want to leave them in your Org files), simply add this to the top of your Org files:

#+hugo_front_matter_key_replace: aliases>nil

5 Replacing the author with authors in front-matter #

Some themes like DoIt support parsing a list of authors from an authors front-matter parameter. But ox-hugo always exports authors as a list to the author front-matter parameter.

You can have ox-hugo export the list of authors to the authors front-matter by adding this to the top of your Org files:

#+hugo_front_matter_key_replace: author>authors

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.