Hugo Section

Specifying the path under Hugo “content” to where the Markdown file should be exported.

Default #

By default, ox-hugo exports all the markdown files to <HUGO_BASE_DIR>/content/posts/.

The “posts” sub-directory default is set in the org-hugo-default-section-directory defcustom variable which a user can customize.

With the below Org file, the post will export to that “posts” sub-directory:

#+hugo_base_dir: .

* My post
:PROPERTIES:
:EXPORT_FILE_NAME: my-post
:END:
This gets created in ~<HUGO_BASE_DIR>/content/posts/~.

Setting org-hugo-default-section-directory will affect globally—All your ox-hugo exported projects.

Setting HUGO_SECTION per file #

If you need to override the default HUGO_SECTION only in an Org file, set the #+hugo_section keyword.

#+hugo_base_dir: .
#+hugo_section: articles

* My post
:PROPERTIES:
:EXPORT_FILE_NAME: my-post
:END:
This gets created in ~<HUGO_BASE_DIR>/content/articles/~.

Setting HUGO_SECTION per subtree (only per-subtree flow) #

If you need to override both the default HUGO_SECTION and the Org file specific #+hugo_section keyword, set the EXPORT_HUGO_SECTION subtree property.

#+hugo_base_dir: .
#+hugo_section: articles

* About
:PROPERTIES:
:EXPORT_HUGO_SECTION: /
:EXPORT_FILE_NAME: about
:END:
This gets created directly in ~<HUGO_BASE_DIR>/content/~.
* My post
:PROPERTIES:
:EXPORT_FILE_NAME: my-post
:END:
This gets created in ~<HUGO_BASE_DIR>/content/articles/~. As the
~EXPORT_HUGO_SECTION~ property is not set, the ~#+hugo_section~
keyword value applies.
* Notes
:PROPERTIES:
:EXPORT_HUGO_SECTION: notes
:END:
** My note
:PROPERTIES:
:EXPORT_FILE_NAME: my-note
:END:
This gets created in ~<HUGO_BASE_DIR>/content/notes/~.

The EXPORT_HUGO_SECTION does not need to be set in the same subtree as the post.

The benefit of this is that you can have a parent subtree set the EXPORT_HUGO_SECTION value, and then have all the children subtrees inherit that value. See the “Notes” subtree in above example to see this inheritance in action.

Section path fragments (only per-subtree flow) #

The default Org Property behavior is that the value of a property set in the closest parent wins. See the below example to understand that.

* Main section
:PROPERTIES:
:EXPORT_HUGO_SECTION: main
:END:
The parsed value of ~EXPORT_HUGO_SECTION~ property is ~"main"~ here.
** Sub section 1
:PROPERTIES:
:EXPORT_HUGO_SECTION: sub
:END:
The parsed value of ~EXPORT_HUGO_SECTION~ property is ~"sub"~ here. The
earlier set ~"main"~ value in the parent of this subtree is lost.

I would have liked the parent value ~"main"~ to get auto-prepended here.
** Sub section 2
:PROPERTIES:
:EXPORT_HUGO_SECTION: main/sub
:END:
The parsed value of ~EXPORT_HUGO_SECTION~ property is ~main/sub~ here.

While this works, it gets a bit inconvenient to manually prefix the
parent property value (~"main/"~ here) as the number of nesting levels
increase.
Code Snippet 1: Using only EXPORT_HUGO_SECTION

But this is Emacs, and with the help of Emacs-Lisp and kind help from Ihor Radchenko on the Org mailing list, ox-hugo now has a solution to this!

    Introducing EXPORT_HUGO_SECTION* (with that asterisk) πŸŽ‰

If a subtree has the EXPORT_HUGO_SECTION* property set, it is treated as a section path fragment. Such fragment properties will be concatenated with the same fragment properties further up in the parent hierarchy.

The collective concatenated value of EXPORT_HUGO_SECTION* properties is further prefixed with the value of the good old HUGO_SECTION keyword/property that’s effective in that subtree.

EXPORT_HUGO_SECTION* has to be set as a subtree property. There is no Org keyword equivalent for this, because this property is designed only for per-subtree flow (and it makes sense only for this flow).

So the final section path looks like this:

<HUGO_BASE_DIR>/content/<HUGO_SECTION>/<concatenated values of EXPORT_HUGO_SECTION*>/
                        └─────────────────────  section path  β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

See the below example to get further clarity on this logic.

* Main section
:PROPERTIES:
:EXPORT_HUGO_SECTION: main
:END:
The /section path/ derived at this level is ~"main/"~.
** Sub section 1
:PROPERTIES:
:EXPORT_HUGO_SECTION*: sub1
:END:
The /section path/ derived at this level is ~"main/sub1/"~.
*** Sub section 1.1
:PROPERTIES:
:EXPORT_HUGO_SECTION*: p1
:END:
The /section path/ derived at this level is ~"main/sub1/p1/"~.
*** Sub section 1.2
:PROPERTIES:
:EXPORT_HUGO_SECTION*: p2
:END:
The /section path/ derived at this level is ~"main/sub1/p2/"~.
** Sub section 2
:PROPERTIES:
:EXPORT_HUGO_SECTION*: sub2
:END:
The /section path/ derived at this level is ~"main/sub2/"~.
Code Snippet 2: Using EXPORT_HUGO_SECTION* in conjunction to EXPORT_HUGO_SECTION
Fork me on GitHub