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.

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:

Here is my *post summary*.

And this can be over /multiple lines/ too!

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

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

Examples #

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

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