[[https://github.com/kaushalmodi/ox-hugo/actions][https://github.com/kaushalmodi/ox-hugo/actions/workflows/test.yml/badge.svg]] [[https://melpa.org/#/ox-hugo][file:https://melpa.org/packages/ox-hugo-badge.svg]] [[https://www.gnu.org/licenses/gpl-3.0][https://img.shields.io/badge/License-GPL%20v3-blue.svg]]
/If you have any questions or if you have anything interesting to share related to ox-hugo, feel free to do so on [[https://github.com/kaushalmodi/ox-hugo/discussions][Discussions]]!/
=ox-hugo= is an Org exporter backend that exports Org to [[https://gohugo.io/][Hugo]]-compatible Markdown ([[https://github.com/russross/blackfriday][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 [[https://ox-hugo.scripter.co/doc/examples/][Real World Examples]] section to quickly jump to sites generated using =ox-hugo= and their Org sources.
Table of Contents
[[#screenshots][Screenshots]]
[[#documentation][Documentation]]
[[#demo][Demo]]
[[#installation][Installation]]
[[#usage][Usage]]
[[#thanks][Thanks]]
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) [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-subtree.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-subtree.png]]
Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content-org/screenshot-subtree-export-example.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content/writing-hugo-blog-in-org-subtree-export.md][Markdown]] ** One post per Org file [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-file.png][https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/doc/static/images/one-post-per-file.png]]
Files in above screenshot :: [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content-org/writing-hugo-blog-in-org-file-export.org][Org]] -> [[https://raw.githubusercontent.com/kaushalmodi/ox-hugo/main/test/site/content/writing-hugo-blog-in-org-file-export.md][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.
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:
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./
The test site uses a [[https://github.com/kaushalmodi/hugo-bare-min-theme][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 [[https://themes.gohugo.io/][Hugo Themes]] for examples of really good site prettification and presentation styles./
You will need to /require/ the package after installing it to get the =ox-hugo= export options 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 [[https://github.com/jwiegley/use-package][=use-package=]], you can do the below instead:
(use-package ox-hugo :ensure t ;Auto-install the package from Melpa :pin melpa ;`package-archives' should already have ("melpa" . "https://melpa.org/packages/") :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 ([[https://github.com/kaushalmodi/ox-hugo/pull/440][ref]])./
Usage
Jump to the [[https://ox-hugo.scripter.co/doc/quick-start/][Quick Start]] section to quickly try out ~ox-hugo~ with Hugo.
** 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/
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:
HUGO_SECTION :: The default Hugo section name for all the posts. See [[https://gohugo.io/content-management/sections/][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 [[https://ox-hugo.scripter.co/doc/hugo-section/][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 [[https://en.wikipedia.org/wiki/Tree_(data_structure)][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_FRAG~ 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". This is same as calling the ~org-hugo-export-wim-to-md~ function interactively or via ~(org-hugo-export-wim-to-md)~ in Emacs Lisp.
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 [[https://en.wikipedia.org/wiki/Tree_(data_structure)][branch/leaf data structure terminlogy]], then the subtrees with =EXPORT_FILE_NAME= property need to be /leaf nodes/.
/Also see the [[https://ox-hugo.scripter.co/doc/auto-export-on-saving/][Auto Exporting]] section./ ** Customization Options Do =M-x customize-group=, and select =org-export-hugo= to see the available customization options for this package.