Usage

Before you export #

Before you export check that these properties are set as you need:

HUGO_BASE_DIR

Root directory of the source for the Hugo site. If this is set to ~/hugo/, the exported Markdown files will be saved to ~/hugo/content/<HUGO_SECTION>/ directory¹. By default, the Markdown files reside in a hierarchy under the content/ directory in the site root directory (ref).

If you try to export without setting this property, you will get this error:

user-error: It is mandatory to set the HUGO_BASE_DIR property
            or the `org-hugo-base-dir' local variable

This property can be set by one of two ways:

1. Setting the #+hugo_base_dir: keyword in the Org file.
2. Setting the org-hugo-base-dir variable in a .dir-locals.el or File Local Variables.

HUGO_SECTION

The default Hugo section name for all the posts. See here for more information on Hugo sections. It is common for this property to be set to posts or blog. The default value is set using org-hugo-default-section-directory. See Hugo Section for details.

Important: If you choose to export an Org subtree as a post, you need to set the EXPORT_FILE_NAME subtree property. That property is used by this package to figure out where the current post starts. For that reason, a subtree with EXPORT_FILE_NAME property cannot nest another subtree with that property. If you can analogize with the branch/leaf data structure terminlogy, then the subtrees with EXPORT_FILE_NAME property need to be leaf nodes.

Export bindings #

The common ox-hugo export bindings are:

For both one-post-per-subtree and one-post-per-file flows #

C-c C-e H H

Export “What I Mean”. This is same as calling the org-hugo-export-wim-to-md function interactively or via (org-hugo-export-wim-to-md) in Emacs Lisp.

• If point is in a valid Hugo post subtree, export that subtree to a Hugo post in Markdown.

  A valid Hugo post subtree is an Org subtree that has the EXPORT_FILE_NAME property set. Note that a subtree with EXPORT_FILE_NAME property cannot nest a subtree with the same property set. If you can analogize with the branch/leaf data structure terminlogy, then the subtrees with EXPORT_FILE_NAME property need to be leaf nodes.

• If the file is intended to be exported as a whole (i.e. has the #+title keyword), export the whole Org file to a Hugo post in Markdown.

C-c C-e H A

Export all “What I Mean”. This is same as executing (org-hugo-export-wim-to-md :all-subtrees) in Emacs Lisp.

• If the Org file has one or more ‘valid Hugo post subtrees’, export them to Hugo posts in Markdown.
• If the file is intended to be exported as a whole (i.e. no ‘valid Hugo post subtrees’ at all, and has the #+title keyword), export the whole Org file to a Hugo post in Markdown.

For only the one-post-per-file flow #

C-c C-e H h

Export the Org file to a Hugo post in Markdown. This is same as calling the org-hugo-export-to-md function interactively.

Also see the Auto Exporting section.

Customization Options #

Do M-x customize-group, and select org-export-hugo to see the available customization options for this package.