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).
The ox-hugo
backend extends from a parent backend
ox-blackfriday.el
. The latter is the one that primarily does the
Blackfriday-friendly Markdown content generation. The main job of
ox-hugo
is to generate the front-matter for each exported content
file, and then append that generated Markdown to it.
There are, though, few functions that ox-hugo.el
overrides over
those by ox-blackfriday.el
.
See the Real World Examples section to quickly jump to sites generated
using ox-hugo
and their Org sources.
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).
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.
Org source → ox-hugo
Exported Markdown → https://ox-hugo.scripter.co/test
The test site uses a minimal theme written just for debug purposes (not extra aesthetics). The test site is designed to verify if all the content translates from Org to Markdown as expected.
See Hugo Themes for examples of really good site prettification and presentation styles.
This package requires emacs 24.4+ and Org 9.0+. It is available on Melpa (https://melpa.org/#/ox-hugo).
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
: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
: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. –
Before you export check that these properties are set as you need:
posts
or
blog
. The default value is set using
org-hugo-default-section-directory
. See
Hugo Section for details.~/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.
The common ox-hugo
export bindings are:
C-c C-e H H
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.
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
#+title
keyword), export
the whole Org file to a Hugo post in Markdown.C-c C-e H h
Do M-x customize-group
, and select org-export-hugo
to see the
available customization options for this package.
org-hugo-pandoc-cite-references-heading
# "References {#references}"
This is the Markdown heading that gets inserted before the section of references inserted by Pandoc inserted (See Pandoc Citations) at the end of the post.
To prevent the insertion of that Markdown heading, set this variable
to an empty string (""
).
http://whyarethingsthewaytheyare.com/setting-up-the-blog/
(not
hyperlinking the link as it is insecure — not https),
http://www.holgerschurig.de/en/emacs-blog-from-org-to-hugo/
(not
hyperlinking the link as it is insecure — not https) and the
goorgeous
project by Chase Adams (@chaseadamsio) for inspiration
to start this project.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). ↩︎