Custom Front-matter Parameters

Setting custom front-matter parameters which have no special meaning to Hugo, but are used in user’s themes.
  • To set a custom front-matter parameter in a subtree, use the :EXPORT_HUGO_CUSTOM_FRONT_MATTER: property.
  • To set a custom front-matter parameter globally or for per-file export flow, use the keyword #+hugo_custom_front_matter:.

For the rest of this section, the property method for setting the custom front-matter will be used. But the same applies to the keyword method too (except for property-specific :EXPORT_HUGO_CUSTOM_FRONT_MATTER+: syntax – See (org) Property Syntax for more).

Single value parameters #

Syntax #

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1 :key2 value2
:END:

Instead of appending all the key/value pairs on the same line, they can instead be broken down as shown below, by appending + to the property name.

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :key2 value2
:END:

If using the keyword method instead, the same would be written as:

#+hugo_custom_front_matter: :key1 value1
#+hugo_custom_front_matter: :key2 value2

The above method of appending keywords will work for the other cases below too.

Example #

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :feature true
:END:

Above exports to TOML front-matter as:

feature = true

List value parameters #

Syntax #

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 '(elem11 elem12) :key2 '(elem21 elem22)
:END:

Example #

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :animals '(dog cat "penguin" "mountain gorilla")
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :integers '(123 -5 17 1_234)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :floats '(12.3 -5.0 -17E-6)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :booleans '(true false)
:END:

Above exports to TOML front-matter as:

animals = ["dog", "cat", "penguin", "mountain gorilla"]
integers = [123, -5, 17, 1_234]
floats = [12.3, -5.0, -1.7e-05]
booleans = [true, false]

Maps of single and list values #

Maps of keys with single or list values are supported. Maps of maps are not supported.

Syntax #

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 '((subkey11 . subval11) (subkey12 . (subelem121 subelem122))) :key2 '((subkey21 . subval21))
:END:

Example #

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :versions '((emacs . "27.0.50") (hugo . "0.48"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header '((image . "projects/Readingabook.jpg") (caption . "stay hungry, stay foolish"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :collection '((animals . (dog cat "penguin" "mountain gorilla")) (integers . (123 -5 17 1_234)) (floats . (12.3 -5.0 -17E-6)) (booleans . (true false)))
:END:

Above exports to TOML front-matter as:

[versions]
  emacs = "27.0.50"
  hugo = 0.48
[header]
  image = "projects/Readingabook.jpg"
  caption = "stay hungry, stay foolish"
[collection]
  animals = ["dog", "cat", "penguin", "mountain gorilla"]
  integers = [123, -5, 17, 1_234]
  floats = [12.3, -5.0, -1.7e-05]
  booleans = [true, false]

More Examples #

You can find many other examples by looking at tests tagged custom-fm.

Fork me on GitHub