Skip to content

Commit

Permalink
doc: How to set the menu front-matter
Browse files Browse the repository at this point in the history 
Fixes #166.
  • Loading branch information
@kaushalmodi
kaushalmodi committed May 13, 2022
1 parent 6c6c0ba commit 5ad69b4
Showing 1 changed file with 203 additions and 0 deletions.
203 changes: 203 additions & 0 deletions doc/ox-hugo-manual.org
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4507,6 +4507,209 @@ This feature has language support too. If the ~#+language~ keyword is
set to a language code other than ~en~ (example: ~de~), the
translations of the element type names get exported. The translations
are based on the ~org-export-dictionary~ variable from ~ox.el~.
*** Menu Front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: menu-front-matter
:END:
#+begin_description
Support for exporting to ~menu~ front-matter.
#+end_description
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:

#+name: code__hugo_menu_entry_visualization
#+caption: Visualization of Hugo Menu Entries
#+begin_src text
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
| +--------------+
. | .. +----> ..
+--------------+
#+end_src

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

#+begin_note
A /Menu Entry/ is uniquely associated with a /Page/.
#+end_note

Here are the valid keys for that ~menu~ config as derived from the
[[https://gohugo.io/variables/menus/#menu-entry-variables][Menu Entry Variables]] documentation:

#+name: tab__menu_config_keys
#+caption: 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:

#+begin_src org
:EXPORT_HUGO_MENU: :menu <menu name> <:key 1> <val 1> <:key 2> <val 2> ..
#+end_src

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:

#+name: tab__menu_front_matter_keys
#+caption: ~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:

#+name: code__common_menu_setting
#+caption: Common style of setting the ~menu~ front-matter
#+begin_src org
,* 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:
#+end_src

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

#+name: code__common_menu_setting_post_1_fm
#+caption: ~menu~ in "Post 1" front-matter
#+begin_src toml
[menu]
[menu.main]
weight = 3001
identifier = "post-1"
#+end_src

#+name: code__common_menu_setting_post_2_fm
#+caption: ~menu~ in "Post 2" front-matter
#+begin_src toml
[menu]
[menu.main]
weight = 3002
identifier = "post-2"
#+end_src

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):
#+begin_src org
:EXPORT_HUGO_MENU: :menu "something here" :weight 80 :parent posts :identifier foo1
#+end_src

, the ~menu~ in the exported front-matter will look like below:
#+begin_src toml
[menu]
[menu."something here"]
parent = "posts"
weight = 80
identifier = "foo1"
#+end_src
**** Overriding Menu Entry keys
#+begin_note
This feature is applicable only to subtree-based flow.
#+end_note
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:

#+name: code__hugo_menu_override_org
#+caption: Example of using ~:EXPORT_HUGO_MENU_OVERRIDE:~
#+begin_src org
,* 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:
#+end_src

With above, "Post 1" ~menu~ front-matter will be exported as:

#+name: code__hugo_menu_override_post_1
#+caption: ~menu~ in "Post 1" front-matter with overridden ~identifier~ and ~weight~ values
#+begin_src toml
[menu]
[menu."something here"]
parent = "posts"
weight = 100
identifier = "abc"
#+end_src

, and "Post 2" ~menu~ front-matter will be exported as:

#+name: code__hugo_menu_override_post_2
#+caption: ~menu~ in "Post 2" front-matter with overridden ~weight~ value
#+begin_src toml
[menu]
[menu."something here"]
identifier = "post-2"
parent = "posts"
weight = 1
#+end_src
** Meta
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu "7.meta"
Expand Down

0 comments on commit 5ad69b4

Please sign in to comment.