Hi Diego,
Post by Diego Zamboniox-hugo takes a different approach: it uses org-modeâs ox-markdown
exporter to produce Markdown from the org source, so that Hugo processes a
Markdown file. This makes a big difference, as each tool is processing its
own native format: org-mode processes org, and Hugo processes Markdown.
That's very well said :)
Post by Diego ZamboniThanks to this, you can even include Hugo shortcodes (
https://gohugo.io/content-management/shortcodes/) in your org-mode
source, and they will be passed untouched to Hugo (this is not entirely
advisable as it makes your source Hugo-specific, but itâs doable if you
want it).
Correct. The aim of ox-hugo is to allow any Org document to be easily
exportable to Hugo, while also allowing the same document to be reusable
for other export formats too.
So I don't recommend embedding Hugo shortcodes directly in Org files (even
if they work.. not guaranteeing that such embedded Hugo shortcodes will
always work). But shortcodes are still supported, though in a different
style, leveraging the Org special blocks. That feature is yet undocumented.
But it is fully implemented, tested (and used by me). See
https://github.com/kaushalmodi/ox-hugo/issues/126 for more info.
Post by Diego ZamboniAnother very nice ox-hugo feature is its âOne post per Org subtreeâ mode (
https://ox-hugo.scripter.co/#screenshot-one-post-per-subtree), in which
you keep your entire post tree (in fact, you could keep your entire
website) in a single Org file. I was skeptical about this at first (who
wants to keep *everything* in a single file), but in practice it works very
well, and allows you to have tags/categories or other attributes per
subtree, so you donât have to repeat them on every post.
That's the primary reason why I started working on ox-hugo. I couldn't bear
the manual labor of copy/pasting/syncing of front-matter across separate
Markdown files. I always suggest people to try the "per-subtree blogging
flow" because Org subtree structure, property and tag inheritance so much
reduce that manual effort. See here on how various properties and tags
translate to Hugo front-matter ->
https://ox-hugo.scripter.co/doc/org-meta-data-to-hugo-front-matter/#for-subtree-based-exports
.
I also have this little annotated diagram:
Loading Image...
Post by Diego ZamboniIf you really want to keep each post in a separate file, that is doable as
well. The ox-hugo website has a lot of very useful information.
Finally, you can do the transition gradually - for my website, I had years
of accumulated Markdown files from my adventures with Jekyll, Octopress and
later Hugo. Those are still in place, and I have started only putting my
new posts in an org file which ox-hugo processes. Since those are converted
to Markdown files, they end up alongside the old hand-crafted files, and
Hugo just processes them all together.
That too! Looks like you hit all the awesome points :) My scripter.co site
source also contains of few dozen old Markdown posts. New stuff is written
in Org and exported to Markdown using ox-hugo which live right along the
old Markdown content... and everything just works.
Post by Diego ZamboniI really recommend ox-hugo, Kaushal has done a fantastic job and he is
also really helpful and responsive with questions.
Thanks for this heavy recommendation. Working on this project and
supporting/making it more robust based on user feedback has been great
pleasure.
Tip: I learned a lot by reading the source files for
Post by Diego Zambonihttps://ox-hugo.scripter.co/ and for https://scripter.co/, both of which
are kept in ox-hugo structure. You can find pointers to those and some
other examples (including my own websites, zzamboni.org and cf-learn.info)
at https://ox-hugo.scripter.co/doc/examples/
Yes! The list of contributors on that Real World Examples page is growing
day by day.
And finally, some clarification about things mentioned in other parts of
this thread:
- Using Hugo does *not* require you to know the Go language. You just learn
the Go templating syntax. And that too, if you want to start by tweaking
and designing Hugo themes. You can always pick one of the 200+ Hugo themes,
and get your blog started, and then revisit writing your own theme at a
later time.
- It doesn't even require you to install the Go toolchain (though it's not
difficult, you just unzip an archive).
- "Installing" hugo is a matter of a single wget of the archive for the OS
of your choice from here: https://github.com/gohugoio/hugo/releases, and
then unarchiving that to somewhere in your PATH.
Apart of the binary-static-ness of the hugo static site generator, another
reason it appealed to me is that the Go templating syntax feels a bit
/lispy/. For example, I use this:
{{ $.Scratch.Set "__repo_updated_time" (index (index (index (index
$repo_json "commit") "commit") "committer") "date") }}
which extracts the commit date by the committer (not author) using GitHub
API for the "Last updated" column on the Real World Examples page:
https://ox-hugo.scripter.co/doc/examples/ (hopefully someone didn't think I
was manually updating all those dates :P)
In summary, ox-hugo allows you to use the best tools for each task: (1)
content writing in Org, and (2) mass HTML/RSS/JSON/etc. generation using
Hugo. The former wins in having a concise Org document where the Org
features of macros, tag/property inheritance, Org babel, etc. can be
leveraged. The latter wins in creating the *whole* site containing
literally hundreds of pages (posts, lists, feeds, search index, JSON feeds,
aliased pages, whatnot) in a matter of *a second or two*.
Kaushal
--
Kaushal Modi
