- 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 or TOML tables of tables are not supported. See Front-matter Extra section for an alternative.
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]
Front-matter Extra #
You would use this feature only if you need to use some front-matter
that ox-hugo cannot translate from native Org keywords/properties to
TOML/YAML front-matter. A good example is if you need to add custom
map of map type front-matter (or TOML tables of tables).
The front-matter specified in this manner is appended verbatim to
the end of the ox-hugo generated front-matter.
TOML Extra front-matter #
Create a toml Org source block anywhere in your post, and add the
special header args :front_matter_extra t to it.
The TOML front-matter is the default. So you do not need to set
:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml.
* Post with TOML front-matter (default)
:PROPERTIES:
:EXPORT_FILE_NAME: extra-front-matter-toml
:END:
The contents of the ~#+begin_src toml :front_matter_extra t~ TOML
block here will get appended to the TOML front-matter.
#+begin_src toml :front_matter_extra t
[[foo]]
bar = 1
zoo = "abc"
[[foo]]
bar = 2
zoo = "def"
#+end_src
YAML Extra front-matter #
Create a yaml Org source block anywhere in your post, and add the
special header args :front_matter_extra t to it.
* Post with YAML front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: extra-front-matter-yaml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
The contents of the ~#+begin_src yaml :front_matter_extra t~ YAML
block here will get appended to the YAML front-matter.
#+begin_src yaml :front_matter_extra t
foo:
- bar: 1
zoo: abc
- bar: 2
zoo: def
#+end_src
Wrong format of extra front-matter #
The :front_matter_extra t source block LANG has to match your
selected front-matter format.
You cannot have a #+begin_src yaml :front_matter_extra t extra
front-matter block if your front-matter format is YAML (and
vice-versa).
If that happens, that blocks gets exported neither to the Markdown body nor to the front-matter.
More Examples #
You can find many other examples by looking at tests tagged custom-fm.
