Ox-Hugo: A carefully crafted Org exporter back-end for Hugo

If you have any questions or if you have anything interesting to share related to ox-hugo, feel free to do so on Discussions!

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.

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)

Files in above screenshot: Org -> Markdown

One post per Org file

Files in above screenshot: Org -> Markdown

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.

Documentation

ox-hugo uses itself to generate its documentation!

https://ox-hugo.scripter.co/

You can generate the same too! Simply clone this repo and do make doc_md.

Make sure you visit the above link to read more on:

Why ox-hugo?
Auto exporting to Markdown each time the Org file is saved
Using Org Capture to start a new blog post
.. and many more topics and examples

Source of the Documentation site

Org source

The documentation site is published by first using ox-hugo to export from Org to Markdown, and then finally hugo. So no Markdown files are committed in the =doc/content/= directory.

Demo

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.

Installation

This package requires at least GNU Emacs 25.3 and Org Mode 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))

Use Package

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)

Spacemacs

Spacemacs users can use ox-hugo by setting the variable org-enable-hugo-support.

(setq-default dotspacemacs-configuration-layers
              '((org :variables
                  org-enable-hugo-support t)))

This was verified to work on Spacemacs =develop= branch (ref).

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[fn:-1-section_more]. 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:

Setting the #+hugo_base_dir: keyword in the Org file.
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.

[fn:-1-section_more] 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).

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

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.

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

`org-hugo-pandoc-cite-references-heading`

Default value: "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 ("").

Changelog

v0.8 <2018-01-26 Fri>

Features

Support exporting content files and attachments (images, documents) to Page Bundles organization structure (Hugo v0.32+) – #111.
Support exporting resources front-matter (Hugo v0.33+) – #115.
Support exporting headless front-matter (Hugo v0.35+).
Advanced table styling is now possible by specifying #+attr_html and #+attr_css (this one is unique to ox-hugo) above Org tables. See its documentation – #93.
- Similarly, support #+attr_html and #+attr_css for paragraphs, example blocks, source blocks, plain lists and quote blocks too – #113.
Now publishDate front-matter property gets auto-derived from the SCHEDULED special property if associated with the valid Hugo post subtree – commit 0807f42d.
- Date values can now be easily set using the C-c . binding in the HUGO_PUBLISHDATE and HUGO_EXPIRYDATE properties too.

Export source blocks and table captions – #38. Here’s a suggested CSS for the captions:

figcaption,
.src-block-caption,
.table-caption {
    font-style: italic;
    text-align: center;
}

Export descriptive or definition lists in Blackfriday-friendly Markdown format – #114.
Support Org Special Blocks like in HTML and LaTeX exports – #105. Here’s one little example:
```
#+begin_mark
/Some/ *marked* text
#+end_mark
    
```
Allow setting :EXPORT_HUGO_SECTION: in the valid Hugo post subtree itself.
Enable replacing any key in the front-matter with anything; it’s even possible to swap the keys now (tags↔categories: commit fb21e82c). New keyword: HUGO_FRONT_MATTER_KEY_REPLACE – see commit b72a5fb0.
Now all the Org keyword values that should get merged, get merged – commit 38eba6d5.
Add title as a valid property of menu front-matter (Hugo v0.32+).

Backward-incompatible changes

A “better user-experience” change.. now you do not need to use double-underscores as space replacement in #+hugo_tags, #+hugo_categories and #+keywords. See this commit for details and examples – commit 319435db.

Fixes

Fix HUGO_LEVEL_OFFSET not getting set – #117, thanks @*shimmy1996*!
Fix internal subtree counter not getting reset after a file-based export.
Fix clickable image links with #+name – commit fef0ec50.
Make title text rendering more robust.. now Markdown markup characters like *, _ and ` show up fine, verbatim, in the title.
Make em dash, en dash, horizontal ellipsis render in post titles too – Hugo #4175 (Upstream bug fix), and in source block captions and table captions too.
Fix double-escaping of # and ![ in Markdown export – #110 (fix in upstream =ox-md.el=).

v0.7 <2017-12-18 Mon>

Features

Now C-c C-e H H works for both per-subtree and per-file flows – commit b1b5d28b.
Support Org heading based internal links – #88.
Support list values for custom front-matter variables – #99.
Support specifying multiple hugo output formats .. Now the outputs front-matter variable is a list.
Support the Org #+author and #+creator keywords and their respective Org Export Options – #106.
Support Org Export Snippets and Export Blocks – commit 1149f20cd.
Now post titles can be set to nil i.e. be not be a part of the front-matter .. because you can.
Improve the messages printed by ox-hugo on doing per-subtree or per-file exports.. the progress of files exported using per-subtree flow is now clearer, and the name of the file exported using per-file flow is now explicit.. Helps when you batch export a dozen files with a mix of these 2 flows.

Backward-incompatible changes

Obsolete org-hugo-export-subtree-∗ functions and replace them with org-hugo-export-wim-∗ (What I Mean) functions. See the doc string of org-hugo-export-wim-to-md for details.
If you are using the Auto-export on saving flow, note the function name change there too!

Fixes

Fix number of backticks in code fence when code contains code fence (pathological corner case).
Better document the HUGO_CODE_FENCE keyword – #102.
Don’t render (c), (r), (tm) inside Latex equations – #104 (Upstream bug workaround).
Better recognition of TOML-compatible integers and floats in meta data for front-matter so that valid integers/floats don’t get unnecessarily double-quoted.

v0.6 <2017-11-09 Thu>

Features

Support the num export option. Now you can prefix all post headings (or some not.. the ones with UNNUMBERED property set to t) with their section numbers – #76.
Org TOC’s are now exported as unordered Markdown lists. This allows having TOC’s with unnumbered headings too! This also enables prefixing the section headings with their full section numbers, and also having only selected headings unnumbered (both in the post body and the TOC).
Add support for exporting internal links to source blocks, tables and images by their block names! – #29.
Org table column alignment markers (<l>, <r>, <c>) are now exported to equivalent Markdown tables.. so a center-aligned column in Org buffer will remain center-aligned in the final HTML too! – #95.
Allow setting multiple Hugo aliases for a post. Also infer the section name from inherited HUGO_SECTION values (subtree-based exports) for those alias prefixes.
Prevent a footnote ref to appear by itself on a newline (based on wrapping) in the browser – #96.
If Hugo shortcodes are used specifically in Markdown (md) source blocks, they will be auto-escaped (useful when you want to document/talk about some Hugo shortcode in a blog post) – #94.
If an Org table has just 1 row, don’t make it render as a header row in the final HTML.
If you have a case where you need to have an Org source block instead a quote block, and then a source block after that quote block (I know, a very common case.. 😉), Blackfriday barfs (Blackfriday #407). But we now have a workaround, which just works – #98.
Now ATTR_HTML above even hyper-linked images works (earlier it worked only above non-hyper-linked images).

Backward-incompatible changes

Org TOC’s are exported as unordered Markdown lists instead of ordered Markdown lists, and now full section numbers (like 1.2.3) are shown in the TOC instead of just the last digit (like 3.) – commit 4be378e7.
The num Org export option is default to nil (only for ox-hugo). So Org TOC’s are exported without section numbers by default. To get section numbers, set num to t or onlytoc.

Fixes

Now exporting 1-row Org tables works too.
Add missing http/https/ftp prefix for hyper-linked images.

v0.5 <2017-11-06 Mon>

Features

Export TOC as a Markdown ordered list. See Table of Contents – #88.
#+attr_html above http/https/ftp links is now supported (useful for specifying the target, rel, attributes, for example).

v0.4.1 <2017-10-29 Sun>

Features

Support specifying the :height parameter in the #+attr_html above image links. That eventually gets transformed to the height parameter in the figure tag in the HTML generated by Hugo. This feature requires building Hugo from its master branch with commit 488631fe (or Hugo v0.31+).

Fixes

Fix EXPORT_HUGO_SECTION not getting inherited #90.

v0.4 <2017-10-28 Sat>

Backward-incompatible changes

Restore the default Org behavior of #+tags. Now that keyword (and the EXPORT_TAGS property) is not used by ox-hugo. Fixes #89.
File-based exports must now use #+hugo_tags to set the post tags.
Subtree-based exports can use the EXPORT_HUGO_TAGS property to override Org-style tags on the same heading (and the ones inherited from Org-style tags from any of the parent subtrees and #+filetags).
- Note that for subtree-based exports, #+filetags can be used to set tags globally in the file. Earlier #+tags was used for that purpose.
Subtree-based exports can use the EXPORT_HUGO_CATEGORIES property to override Org-style categories (tags with “@” prefix) on the same heading (and the ones inherited from Org-style categories from any of the parent subtrees and #+filetags).
- Note that for subtree-based exports, #+filetags can be used to set categories (tags with “@”) globally in the file.

See the new section added to documentation: *Tags and Categories*

Features

Support specifying the :width parameter in the #+attr_html above image links. That eventually gets transformed to the width parameter in the figure tag in the HTML generated by Hugo.

v0.3.2 <2017-10-24 Tue>

Fixes

Fix issue with heading metadata parsing (ALLTAGS, CLOSED, TODO) when a post Org heading was immediately followed by that post’s sub-heading. This issue was seen in subtree-based exports #87.

v0.3.1 <2017-10-19 Thu>

Fixes

Fix the source block line number annotation when the line numbers increased in number of digits in the same code block.

v0.3 <2017-10-18 Wed>

Features

Source blocks can now be exported with line numbers and/or highlighting!
See Source Blocks for details.

v0.2.3 <2017-10-11 Wed>

Fixes

org-hugo-slug earlier stripped off only the code HTML tag (<code> .. </code>) from the input string, if present. Now it does that for any HTML tag, like span. For example, this HTML gets stripped off from the above heading (only inside org-hugo-slug when deriving the slug string): ~<2017-10-11 Wed>~.

v0.2.2 <2017-10-10 Tue>

Backward-incompatible changes

Now ox-hugo by default requires text, to be sub/super-scripted, to be wrapped in {}. So now a_b will be exported as a_b, but a_{b} will be exported as ab. To revert back to the earlier behavior, user needs to add #+options: ^:t to their Org file.

v0.2.1 <2017-09-28 Thu>

Fixes

Single column tables now export correctly #84.
Ignore HUGO_WEIGHT set to auto for per-file exports #83.

v0.2 <2017-09-27 Wed>

Features

Add support for all Hugo figure shortcode parameters #79.
New option org-hugo-delete-trailing-ws defaults to t; now Hugo deletes trailing white-spaces by default.
New options org-hugo-default-static-subdirectory-for-externals and org-hugo-external-file-extensions-allowed-for-copying (related to #69).

Fixes

Remove HUGO_STATIC_IMAGE option; fix attachment re-write #69.
Fix incorrectly inserted hard line-breaks #72. Added a new option HUGO_PRESERVE_FILLING.
Fix error happening when a post title was set to an empty string [ ba9e8365 ].

Backward-incompatible changes

Switch the default value of org-hugo-use-code-for-kbd option to nil [ 88ba15ae ].

v0.1.3 <2017-09-13 Wed>

Now a HUGO key value set to "nil", like #+hugo_code_fence: nil, will evaluate as nil instead of t, as now org-hugo--plist-get-true-p is used to parse boolean keys instead of plist-get.

v0.1.2 <2017-09-12 Tue>

Make DateTime matching better; new internal variable org-hugo--date-time-regexp. Earlier time zones ahead of UTC (with + sign) were not detected as dates in org-hugo--quote-string and thus were unnecessarily quoted.

v0.1.1 <2017-09-11 Mon>

Use CLOSED log drawer info if available to set the date in front-matter #68.
Code optimization: Use of org-entry-get at places instead of maintaining global variables.

Thanks

Matt Price (@titaniumbones)
Puneeth Chaganti (@punchagan)
Also thanks to 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.

Files

README.org

Latest commit

History

README.org

File metadata and controls

Ox-Hugo: A carefully crafted Org exporter back-end for Hugo

Table of Contents

Screenshots

One post per Org subtree (preferred)

One post per Org file

Editorial

Documentation

Source of the Documentation site

Demo

Installation

Use Package

Spacemacs

Usage

Before you export

Export bindings

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

For only the one-post-per-file flow

Customization Options

org-hugo-pandoc-cite-references-heading

Changelog

v0.8 <2018-01-26 Fri>

Features

Backward-incompatible changes

Fixes

Meta

v0.7 <2017-12-18 Mon>

Features

Backward-incompatible changes

Fixes

Meta

v0.6 <2017-11-09 Thu>

Features

Backward-incompatible changes

Fixes

Meta

v0.5 <2017-11-06 Mon>

Features

v0.4.1 <2017-10-29 Sun>

Features

Fixes

v0.4 <2017-10-28 Sat>

Backward-incompatible changes

Features

v0.3.2 <2017-10-24 Tue>

Fixes

v0.3.1 <2017-10-19 Thu>

Fixes

v0.3 <2017-10-18 Wed>

Features

v0.2.3 <2017-10-11 Wed>

Fixes

v0.2.2 <2017-10-10 Tue>

Backward-incompatible changes

v0.2.1 <2017-09-28 Thu>

Fixes

v0.2 <2017-09-27 Wed>

Features

Fixes

Backward-incompatible changes

v0.1.3 <2017-09-13 Wed>

v0.1.2 <2017-09-12 Tue>

v0.1.1 <2017-09-11 Mon>

Thanks

`org-hugo-pandoc-cite-references-heading`