Org to Markdown for Hugo

ox-hugo is an Org exporter backend that exports Org to Hugo-compatible Markdown (Blackfriday) and also generates the front-matter (in TOML or YAML format).

This project consists of ox-blackfriday.el too. It is a derivation of ox-gfm with support added for Blackfriday Markdown tables and many other tweaks. ox-hugo backend extends from this.

Screenshots

Before you read further, you can see below how ox-hugo translates Org to Markdown (Org on the left; exported Markdown with Hugo front-matter on the right).

One post per Org subtree (preferred)

One post per Org file

Editorial

The preferred way to organize the posts is as Org subtrees (also the main reason to write this package, as nothing like that was out there) as it makes the meta-data management for Hugo front-matter pretty effortless.

If you are a one Org-file per post type of a person, that flow works too! Just note that in this flow many of those #+HUGO_ properties need to be managed manually.. just as one would manage the front-matter in Markdown files — See the Org versions in the above screenshots for comparison.

Demo

Org source → Exported Markdown → Hugo published test site

Now, the test site doesn’t look pretty, I know :) .. because:

  • It is designed to verify if all the content translates from Org to Markdown as expected.
  • It uses a bare_min theme written just for the debug purpose (not presentation).

See Hugo Themes for examples of really good site prettification and presentation styles.

Actual usage examples

Installation

This package requires emacs 24.5+ and Org 9.0+. It is available on Melpa (https://melpa.org/#/ox-hugo).

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:

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

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

(use-package ox-hugo
  :after ox)

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
    :ensure t                           ;Auto-install the package from Melpa
    :after ox))

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

Verified to work on Spacemacs develop branch with spacemacs-base distribution, emacs editing style.

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.

  • 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

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:

Binding Description
C-c C-e H H Export only the current valid subtree (has the EXPORT_FILE_NAME property set)
C-c C-e H A Export all valid subtrees (those that have the EXPORT_FILE_NAME property set)
C-c C-e H h Export the whole Org file to a single post

Customization Options

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

Thanks