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.
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_FRAG 🎉
If a subtree has the EXPORT_HUGO_SECTION_FRAG property set1,
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_FRAG
properties is further prefixed with the value of the good old
HUGO_SECTION keyword/property that’s effective in that subtree.
EXPORT_HUGO_SECTION_FRAG has to be set as a subtree
property. There is no Org keyword equivalent for this, because this
property is designed (and makes sense) only for the per-subtree
flow.
So the final section path looks like this:
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_FRAG: sub1
:END:
The /section path/ derived at this level is ~"main/sub1/"~.
*** Sub section 1.1
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: p1
:END:
The /section path/ derived at this level is ~"main/sub1/p1/"~.
*** Sub section 1.2
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: p2
:END:
The /section path/ derived at this level is ~"main/sub1/p2/"~.
** Sub section 2
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: sub2
:END:
The /section path/ derived at this level is ~"main/sub2/"~.
-
If you are looking for
EXPORT_HUGO_SECTION*property, that has been deprecated; please see Deprecation Notices. ↩︎
