#+title: Ox-Hugo: A carefully crafted Org exporter back-end for Hugo #+author: Kaushal Modi [[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.
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: #+begin_src emacs-lisp (with-eval-after-load 'ox (require 'ox-hugo)) #+end_src ** Use Package If you use [[https://github.com/jwiegley/use-package][=use-package=]], you can do the below instead: #+begin_src emacs-lisp (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) #+end_src
** Spacemacs Spacemacs users can use =ox-hugo= by setting the variable =org-enable-hugo-support=.
#+begin_src emacs-lisp (setq-default dotspacemacs-configuration-layers '((org :variables org-enable-hugo-support t))) #+end_src
/This was verified to work on Spacemacs =develop= branch ([[https://github.com/kaushalmodi/ox-hugo/pull/440][ref]])./
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 ([[https://gohugo.io/content-management/organization/][ref]]).
If you try to export without setting this property, you will get this error: #+begin_example user-error: It is mandatory to set the HUGO_BASE_DIR property or the `org-hugo-base-dir' local variable #+end_example 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
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 [[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/.
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.
/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.