Back to top

Menu Front-matter

Support for exporting to menu front-matter.

In Hugo, the global site variable contains a dictionary called Menus. Within Menus, a Menu Name is used to reference a collection or slice of Menu Entries. Each of those Menu Entries are associated with a Page. One can visualize the relationship of those objects in this manner:

site
    Menus
       |                     +--------------+
       +-- "Menu Name 1" --> | Menu Entry 1 +----> Page 1
       |                     +--------------+
       |                     | Menu Entry 2 +----> Page 2
       |                     +--------------+
       |                     | ..           +----> ..
       |                     +--------------+
       |
       |                     +--------------+
       +-- "Menu Name 2" --> | Menu Entry a +----> Page a
       |                     +--------------+
       |                     | Menu Entry b +----> Page b
       |                     +--------------+
       .                     | ..           +----> ..
                             +--------------+
Code Snippet 1: Visualization of Hugo Menu Entries

So on each Page, the user can specify the keys of the associated Menu Entry using the menu front-matter.

A Menu Entry is uniquely associated with a Page.

Here are the valid keys for that menu config as derived from the Menu Entry Variables documentation:

Table 1: Menu Entry keys and associated variables accessible from Hugo template
Menu Entry Key Menu Entry Variable Brief Description
[menu.NAME] .Menu Name of the Menu containing the current Menu Entry
url .URL URL that this Menu Entry points to, defaults to page’s .RelPermalink
identifier .Identifier Identifier is the unique string used to identify this Menu Entry
name .Name Name of this Menu Entry, defaults to page’s .LinkTitle
pre .Pre HTML string that can be used to prefix the Menu Entry .Name
post .Post HTML string that can be used to postfix the Menu Entry .Name
weight .Weight Weight for this Menu Entry, used for sorting menus in a sidebar
parent .Parent Name or Identifier of this Menu Entry’s Parent Menu Entry
title .Title (this is a function) Used to set this Menu Entry’s link’s title attribute, defaults to page’s .LinkTitle

:EXPORT_HUGO_MENU: and #+hugo_menu: #

In Org mode, these Menu Entry keys are specified using the :EXPORT_HUGO_MENU: property (subtree-based exports) or #+hugo_menu: keyword (file-based exports). They are set in this property list form:

:EXPORT_HUGO_MENU: :menu <menu name> <:key 1> <val 1> <:key 2> <val 2> ..

The :menu key is mandatory because that’s used to specify the current Page’s Menu Entry’s parent Menu name.

The rest of the property list keys map directly with the Menu Entry keys shown below:

Table 2: menu Front Matter keys
:EXPORT_HUGO_MENU: or #+hugo_menu: key Menu Entry Front-matter Note
:menu VAL [menu.VAL] mandatory
:identifier VAL identifier = VAL Gets auto-set to the sanitized post title if not set
:weight VAL weight = VAL Gets auto-set based on post subtree’s location if not set
:url VAL url = VAL optional
:pre VAL pre = VAL optional
:name VAL name = VAL optional
:post VAL post = VAL optional
:parent VAL parent = VAL optional
:title VAL title = VAL optional

General use example #

For subtree-based exports, it would be common to specify the container Menu name in a parent subtree and let that value trickle down to the nest post subtrees as a result of Org property inheritance.

It would look something like this:

* Posts under the ~main~ Menu
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu main
:END:
** Post 1
:PROPERTIES:
:EXPORT_FILE_NAME: post-1
:END:
** Post 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-2
:END:
Code Snippet 2: Common style of setting the menu front-matter

When these posts are exported, the menu front-matter in them will look something like this:

[menu]
  [menu.main]
    weight = 3001
    identifier = "post-1"
Code Snippet 3: menu in "Post 1" front-matter 

[menu]
  [menu.main]
    weight = 3002
    identifier = "post-2"
Code Snippet 4: menu in "Post 2" front-matter

Note that the weight and identifier were set automatically by ox-hugo as they were not specified.

Example where more menu keys are specified #

For a post with the below property (subtree-based export):

:EXPORT_HUGO_MENU: :menu "something here" :weight 80 :parent posts :identifier foo1

, the menu in the exported front-matter will look like below:

[menu]
  [menu."something here"]
    parent = "posts"
    weight = 80
    identifier = "foo1"

Overriding Menu Entry keys #

This feature is applicable only to subtree-based flow.

Use the :EXPORT_HUGO_MENU_OVERRIDE: property if you need to override only some of the inherited Menu Entry keys.

Here’s an example Org snippet:

* Parent subtree
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "something here" :parent posts
:END:
** Post 1
:PROPERTIES:
:EXPORT_FILE_NAME: foo
:EXPORT_HUGO_MENU_OVERRIDE: :identifier "abc" :weight 100
:END:
** Post 2
:PROPERTIES:
:EXPORT_FILE_NAME: bar
:EXPORT_HUGO_MENU_OVERRIDE: :weight 1
:END:
Code Snippet 5: Example of using :EXPORT_HUGO_MENU_OVERRIDE:

With above, “Post 1” menu front-matter will be exported as:

[menu]
  [menu."something here"]
    parent = "posts"
    weight = 100
    identifier = "abc"
Code Snippet 6: menu in "Post 1" front-matter with overridden identifier and weight values

, and “Post 2” menu front-matter will be exported as:

[menu]
  [menu."something here"]
    identifier = "post-2"
    parent = "posts"
    weight = 1
Code Snippet 7: menu in "Post 2" front-matter with overridden weight value
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