ox-hugo

ox-hugo is an Org-mode export backend that converts Org files and subtrees into Hugo-compatible Markdown with auto-generated TOML or YAML front-matter, built by Kaushal Modi as a free GPL v3 package for GNU Emacs.

What is ox-hugo?

ox-hugo is an exporter backend for GNU Emacs Org mode that converts Org content into Markdown formatted for Hugo's Blackfriday renderer, and generates the Hugo front-matter in TOML or YAML. It takes Org files or Org subtrees as input and outputs Markdown files with front-matter ready to place in a Hugo site's content directory. The package requires GNU Emacs 26.3 or newer and Org Mode 9.0 or newer, and is distributed through Melpa.

Key Features

• One-post-per-subtree export — Export each Org subtree that carries an EXPORT_FILE_NAME property as its own Hugo post, allowing many posts to live in a single .org file; subtrees with this property cannot nest another such subtree (they must be leaf nodes).
• Automatic front-matter generation — Generates Hugo front-matter in TOML or YAML directly from Org properties, removing the need to hand-write Markdown front-matter.
• Two export flows — Supports both the preferred one-post-per-subtree workflow and an alternative one-post-per-file workflow, with separate export bindings for each (C-c C-e H H and H A for subtree/all, C-c C-e H h for file).
• Auto-export on save — Can automatically re-export the Org file to Markdown each time it is saved, with setup covered in the documentation.
• Org Capture integration — The docs describe using Org Capture to start a new blog post, turning capture into a publishing step.
• Customizable via Emacs options — Run M-x customize-group and select org-export-hugo to adjust available options; the HUGO_BASE_DIR property or org-hugo-base-dir variable controls where output files are written.
• Self-generated documentation — The ox-hugo documentation site (ox-hugo.scripter.co) is produced by ox-hugo itself exporting Org to Markdown and then running Hugo, so no Markdown is committed in its doc/content directory.
• Test site for validation — The repository includes a test site with Org sources exported to Markdown and published, designed to verify that all content translates as expected.

Who is it for?

ox-hugo is for Emacs users who write in Org mode and publish with the Hugo static site generator. It suits bloggers who want to keep all posts in one Org file, technical writers generating documentation from Org, and developers who prefer controlling Hugo front-matter through Org properties instead of editing Markdown manually.

What can you do with ox-hugo?

• Org-mode bloggers — Write posts as Org subtrees under a file with #+title, set EXPORT_FILE_NAME and #+hugo_ properties, then run C-c C-e H H to export the current subtree to a Hugo post in Markdown with front-matter.
• Technical documenters — Use the one-post-per-file flow with C-c C-e H h to export an entire Org file to a single Hugo post, preserving Org syntax and code blocks in the Blackfriday Markdown output.
• Emacs power users — Install with use-package (:ensure t :pin melpa), enable org-enable-hugo-support in Spacemacs, and trigger exports via the Org Export Dispatcher menu that appears with C-c C-e.

How does ox-hugo work?

ox-hugo extends the ox-blackfriday.el backend, which performs the Markdown content generation, while ox-hugo adds the front-matter. When an export binding is invoked, it reads Org properties such as HUGO_BASE_DIR and HUGO_SECTION to determine the destination directory, then exports either the subtree at point (if it has EXPORT_FILE_NAME) or the whole file, writing the resulting Markdown with front-matter into the Hugo content directory.

FAQ

Is ox-hugo free?

Yes, ox-hugo is free software released under the GNU GPL v3 license.

What are the system requirements for ox-hugo?

ox-hugo requires GNU Emacs version 26.3 or newer and Org Mode version 9.0 or newer. It is recommended to install it from Melpa (not Melpa Stable).

How do I install ox-hugo?

Install the ox-hugo package from Melpa, then require it after ox is loaded using (with-eval-after-load 'ox (require 'ox-hugo)). With use-package, add the snippet shown in the repository README to your configuration.

Does ox-hugo export both subtrees and whole files?

Yes. The preferred workflow exports Org subtrees that have the EXPORT_FILE_NAME property, and the alternative workflow exports a whole Org file when no such subtree is present. Both are accessible from the Org Export Dispatcher with the H prefix.