Back to top

Org meta-data to Hugo front-matter

Front-matter format #

ox-hugo supports exporting the front-matter in TOML (default) or YAML.

To change the default to YAML for your exports, add this to the top of your Org files:

#+hugo_front_matter_format: yaml
Subtree-based exports only
If you want only specific subtrees to have the front-matter exported to YAML format, add this to that subtree’s property drawer: 
:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:

For subtree-based exports #

When organizing the posts as Org subtrees, many Hugo front-matter variables get set implicitly using the meta-data parsed from the posts in Org.

Below, where subtree is mentioned, it implies a valid Hugo-post subtree i.e. an Org subtree that has the EXPORT_FILE_NAME property set.

Table 1: Hugo front-matter translation for subtree-based exports
Hugo front-matter (TOML) Org Org description
title = "foo" * foo Subtree heading
date = 2017-09-11T14:32:00-04:00 CLOSED: [2017-09-11 Mon 14:32] Auto-inserted CLOSED subtree property when switch to Org DONE state
date = 2017-07-24 :EXPORT_DATE: 2017-07-24 Subtree property
publishDate = 2018-01-26 SCHEDULED: <2018-01-26 Fri> Auto-inserted SCHEDULED subtree property using default C-c C-s binding
publishDate = 2018-01-26 :EXPORT_HUGO_PUBLISHDATE: 2018-01-26: Subtree property
expiryDate = 2999-01-01 :EXPORT_HUGO_EXPIRYDATE: 2999-01-01: Subtree property
lastmod = <current date> :EXPORT_HUGO_AUTO_SET_LASTMOD: t Subtree property
lastmod = <current date> #+hugo_auto_set_lastmod: t Org keyword
tags = ["toto", "zulu"] * foo :toto:zulu: Subtree heading tags
categories = ["x", "y"] * foo :@x:@y: Subtree heading tags with @ prefix
draft = true * TODO foo Subtree heading Org TODO state set to TODO1.
draft = false * foo or * DONE foo Subtree heading Org TODO state not set or set to DONE1.
weight = 123 (manual) :EXPORT_HUGO_WEIGHT: 123 Manual setting of page weight
weight = 123 (auto-calc) :EXPORT_HUGO_WEIGHT: auto When set to auto, page weight is auto-calculated
tags_weight = 123 (manual) :EXPORT_HUGO_WEIGHT: :tags 123 Manual setting of FOO taxonomy weight, by setting to :FOO VALUE
tags_weight = 123 (auto-calc) :EXPORT_HUGO_WEIGHT: :tags auto When set to :FOO auto, FOO taxonomy weight is auto-calculated
weight = 123 (in [menu.foo]) :EXPORT_HUGO_MENU: :menu foo Menu weight is auto-calculated unless specified

Also see the Custom Front-matter Parameters section.

Front-matter Precedence #

Precedence for date parsing
  1. First transition to a DONE state recorded in :LOGBOOK: (see Dates parsed from :LOGBOOK: drawers)
  2. CLOSED subtree property
  3. EXPORT_DATE subtree property
  4. #+date: keyword
Precedence for lastmod parsing
  1. Last (second or later) transition to a DONE state recorded in :LOGBOOK:, or timestamp of the last added note (see Dates parsed from :LOGBOOK: drawers)
  2. lastmod set automatically if :EXPORT_HUGO_AUTO_SET_LASTMOD: t and if it’s not derived from the :LOGBOOK: drawer.
  3. EXPORT_HUGO_LASTMOD subtree property or #+hugo_lastmod: keyword
Precedence for draft parsing
  1. Org TODO state based draft state
  2. EXPORT_HUGO_DRAFT subtree property

For file-based exports #

Table 2: Hugo front-matter translation for file-based exports
Hugo front-matter (TOML) Org
title = "foo" #+title: foo
date = 2017-07-24 #+date: 2017-07-24
publishDate = 2018-01-26 #+hugo_publishdate: 2018-01-26
expiryDate = 2999-01-01 #+hugo_expirydate: 2999-01-01
lastmod = <current date> #+hugo_auto_set_lastmod: t
tags = ["toto", "zulu"] #+hugo_tags: toto zulu
categories = ["x", "y"] #+hugo_categories: x y
draft = true #+hugo_draft: true
draft = false #+hugo_draft: false
weight = 123 #+hugo_weight: 123
tags_weight = 123 #+hugo_weight: :tags 123
categories_weight = 123 #+hugo_weight: :categories 123
weight = 123 (in [menu.foo]) #+hugo_menu: :menu foo :weight 123

Notes #

  • The auto calculation of weights for pages, taxonomies and menu items works only for subtree-based exports.

    For the file-based exports, the weights have to be specified manually. Any weight assignment to "auto" for file-based exports is ignored.

  • See org-hugo-date-format for customizing the date formats for all date front-matter parameters.

  • For setting custom front-matter parameters, see the Custom Front-matter Parameters section.

  1. The TODO / DONE keyword is used in this example as they are the defaults in org-todo-keywords. If you have customized your org-todo-keywords, or are customizing them using other means like the per-file #+seq_todo setting, use those instead. Use your custom “DONE” keyword (it should be a part of org-done-keywords) instead of the default DONE. And similarly, use your custom “TODO” keyword instead of the default TODO (ensure that it is not in org-done-keywords). ↩︎ ↩︎

Exported from ox-hugo-manual.org using Emacs 26.3 + Org mode 9.6.20 + ox-hugo and published using Hugo 0.101.0 + Onyx
Fork me on GitHub