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.
ox-hugo
uses itself to generate its documentation!
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
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.
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:
(require 'ox-hugo-auto-export) ;If you want the auto-exporting on file saves
(with-eval-after-load 'ox
(require 'ox-hugo))
If you use =use-package=, you can do the below instead:
(use-package ox-hugo-auto-export) ;If you want the auto-exporting on file saves
(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-auto-export) ;If you want the auto-exporting on file saves
(use-package ox-hugo
:ensure t ;Auto-install the package from Melpa (optional)
:after ox))
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. –
<2017-10-09 Mon>/
Before you export check that these properties are set as you need:
- 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
orblog
. The default value is set usingorg-hugo-default-section-directory
. See Hugo Section for details. - 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 thecontent/
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.
[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).
The common ox-hugo
export bindings are:
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 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.
- If point is in a valid Hugo post subtree, export that
subtree 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.
C-c C-e H h
- Export the Org file to a Hugo post in Markdown.
Do M-x customize-group
, and select org-export-hugo
to see the
available customization options for this package.
- 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 toox-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.
- Similarly, support
- Now
publishDate
andexpiryDate
front-matter properties get auto-derived fromSCHEDULED
andDEADLINE
special properties if associated with the valid Hugo post subtree – commit 0807f42d.- Date values can now be easily set using the
C-c .
binding in theHUGO_PUBLISHDATE
andHUGO_EXPIRYDATE
properties too.
- Date values can now be easily set using the
- 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 ofmenu
front-matter (Hugo v0.32+).
- 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.
- 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=).
- Re-write the logic for parsing meta-data for various kinds of dates, and optimize the logic for parsing newline separated lists like tags and categories.
- The
hugo-bare-min-theme
used for the test site is made more portable (at some point, that theme might be moved to a separate repo).
- 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.
- 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!
- 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.
- Add a =debugprint.html= partial to help pretty-print various Hugo objects like Page Params, File and SiteInfo for debug on the test site.
- The test site now has tags and categories pages.
- Add few real world example posts containing complex Latex equations: 1, 2.
- Turns out
ox-hugo
works on emacs 24.4 too (but please upgrade to the latest Emacs and Org stable versions!).
- Support the
num
export option. Now you can prefix all post headings (or some not.. the ones withUNNUMBERED
property set tot
) 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).
- 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 tonil
(only forox-hugo
). So Org TOC’s are exported without section numbers by default. To get section numbers, setnum
tot
oronlytoc
.
- Now exporting 1-row Org tables works too.
- Add missing http/https/ftp prefix for hyper-linked images.
- Add documentation on how you can have Images live in the same directory as Org source – #91.
- Now only Org files for the documentation site need to be committed
to git.
ox-hugo
then exports those to Markdown, and then Hugo publishes those to HTML (as before) — all on Netlify. - Be sure to check out the moderately revamped Test Site. That might
be of interest even if you want to check out what the new features
and changes look like, without first installing/updating
ox-hugo
yourself 😄.
- 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 thetarget
,rel
, attributes, for example).
- Support specifying the
:height
parameter in the#+attr_html
above image links. That eventually gets transformed to theheight
parameter in thefigure
tag in the HTML generated by Hugo. This feature requires building Hugo from its master branch with commit 488631fe (or Hugo v0.31+).
- Fix
EXPORT_HUGO_SECTION
not getting inherited #90.
- Restore the default Org behavior of
#+tags
. Now that keyword (and theEXPORT_TAGS
property) is not used byox-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 headline (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.
- Note that for subtree-based exports,
- Subtree-based exports can use the
EXPORT_HUGO_CATEGORIES
property to override Org-style categories (tags with “@” prefix) on the same headline (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.
- Note that for subtree-based exports,
See the new section added to documentation: *Tags and Categories*
- Support specifying the
:width
parameter in the#+attr_html
above image links. That eventually gets transformed to thewidth
parameter in thefigure
tag in the HTML generated by Hugo.
- Fix issue with headline 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.
- Fix the source block line number annotation when the line numbers increased in number of digits in the same code block.
- Source blocks can now be exported with line numbers and/or
highlighting!
See Source Blocks for details.
org-hugo-slug
earlier stripped off only thecode
HTML tag (<code> .. </code>
) from the input string, if present. Now it does that for any HTML tag, likespan
. For example, this HTML gets stripped off from the above heading (only insideorg-hugo-slug
when deriving the slug string): ~<span class=”timestamp-wrapper”><span class=”timestamp”><2017-10-11 Wed></span></span>~.
- Now
ox-hugo
by default requires text, to be sub/super-scripted, to be wrapped in{}
. So nowa_b
will be exported asa_b
, buta_{b}
will be exported asa<sub>b</sub>
. To revert back to the earlier behavior, user needs to add#+options: ^:t
to their Org file.
- Single column tables now export correctly #84.
- Ignore
HUGO_WEIGHT
set toauto
for per-file exports #83.
- Add support for all Hugo
figure
shortcode parameters #79. - New option
org-hugo-delete-trailing-ws
defaults tot
; now Hugo deletes trailing white-spaces by default. - New options
org-hugo-default-static-subdirectory-for-externals
andorg-hugo-external-file-extensions-allowed-for-copying
(related to #69).
- 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].
- Switch the default value of
org-hugo-use-code-for-kbd
option tonil
[88ba15ae].
- Now a HUGO key value set to
"nil"
, like#+hugo_code_fence: nil
, will evaluate as nil instead of t, as noworg-hugo--plist-get-true-p
is used to parse boolean keys instead ofplist-get
.
- 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 inorg-hugo--quote-string
and thus were unnecessarily quoted.
- 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.
- 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.