Usage

Once the package is installed, you will need to require it so that the ox-hugo export options are available in the Org Export Dispatcher menu (the one you see when you hit C-c C-e to initiate any export).

You can do that by adding the below to your config:

(require 'ox-hugo-auto-export) ;If you want the auto-exporting on file saves

(with-eval-after-load 'ox
  (require 'ox-hugo))

If you use use-package, you can do the below instead:

(use-package ox-hugo-auto-export) ;If you want the auto-exporting on file saves

(use-package ox-hugo
  :ensure t            ;Auto-install the package from Melpa (optional)
  :after ox)

Also see the Auto Exporting section.

Spacemacs

Spacemacs users can choose to add this snippet to their dotspacemacs/user-config function in .spacemacs:

(defun dotspacemacs/user-config ()
  ;; Other stuff
  ;; ..

  ;; ox-hugo config
  (use-package ox-hugo-auto-export) ;If you want the auto-exporting on file saves

  (use-package ox-hugo
    :ensure t          ;Auto-install the package from Melpa (optional)
    :after ox))

You do have have to use the use-package version when using Spacemacs. That version was used because use-package is installed by default in Spacemacs.

If you do so, you also need to add ox-hugo to dotspacemacs-additional-packages.

This was verified to work on Spacemacs develop branch with spacemacs-base distribution, emacs editing style. – <2017-10-09 Mon>

Before you export #

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

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.
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>/ directory1. 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

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.

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”.

  • 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 has the EXPORT_FILE_NAME property set.

  • 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”

  • 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.

Customization Options #

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


  1. The HUGO_SECTION is the bare-minimum requirement to specify the destination path. That path can be further tweaked using HUGO_BUNDLE key (and the associated EXPORT_HUGO_BUNDLE property), and the EXPORT_HUGO_SECTION* property (only for per-subtree exports). [return]
Fork me on GitHub