How to use Org mode with Hugo?

I am an org-mode user. Is there any tutorial showing how to use org-mode with Hugo?

1 Like

/cc @chaseadamsio

Hey @Sergio_Bacelar! The “bad” news is that so far there is no tutorial for how to use files written in org-mode syntax in Hugo…but the good news is that it’s really as simple as dropping an org-mode file with the .org extension in the content directory of your hugo site and letting hugo do all the heavy lifting. Anything you knew about Hugo with markdown applies to Hugo with org-mode.

There’s still a gap between what Hugo renders and the what the org syntax specifies, but I’m working to close the gap as often as I get a chance to sit down and work on it.


Thank you. I will try to create a little example.

So, there is no need to “tell” Hugo that we are using org and not md files. I suppose it’s not acceptable to use both types simultaneously.

This may be a silly question, but what about pandoc to convert org-mode to markdown or html?

  • You can mix all types in the same Hugo site simultaneously (either by name (*.md, *.org etc.) or by markdown=org etc. in front matter)).
  • You can not mix different types in the same content file. Not sure how that would work.

Why would you want that when Hugo has native org-mode support?

I realize I was not clear at all AND that was a silly question. I have not tried org-mode with Hugo, although I like it very much. So I don’t know how far is the roadmap for it.

But as Pandoc have already implemented it, I was wondering about using pandoc as a library.

Anyway this would be a workaround, and native support is far better.

@Sergio_Bacelar, as @bep said, you can have any file types you want, I have .md and .org files in my content (although I’ll likely convert everything over to org-mode over time). Hugo’s great in that way, it’s flexible!

@lebarde there are people who don’t want Hugo to render their org-mode content today (because some of the advanced features are still in the go implementation roadmap). I recommend that they use Emacs org rendering since they’re likely already using Emacs to edit their files. AFAIK, Pandoc has the same problem the go implementation has—org-mode spec is a moving target so maintaining parity is difficult.

Totally right!

I can’t find any Tutorial even after almost a year! Anyone know of one? @chaseadamsio

What have you tried and what doesn’t work? Simply have as content files and use TOML (or YAML) front-matter in there. Write the rest of the post in Org mode. Basic Org syntax is supported using the Goorgeous package that Hugo uses for Org parsing.

For native 100% Org support, I have developed (and still maintain) the ox-hugo package for Emacs. There are many examples of how people use ox-hugo for their Hugo sites.

1 Like

I want to use Hugo’s default support for org files before going ahead and trying ox-hugo package.
I have written up in my Gitlab repo and I use netlify to generate, but no posts show up there. I initially had some .md files in the same location which worked perfectly. Can you please tell me what I am doing wrong? @kaushalmodi Thanks in advance!

The pages generate fine* locally (see below). I believe you are facing a separate issue… that with deploying using Netlify (most likely you are not setting HUGO_VERSION on Netlify, and so Netlify defaults to an antique version of Hugo?)

*: The pages generate, but as I mentioned earlier, only basic Org syntax is supported. So while *bold*, /italics/, etc. work, you can see above that the latex blocks, super-scripting, etc. do not. (Here’s how the same# Org file renders using ox-hugo.)

#: Almost the same… needed few Org syntax fixes.

Thanks a lot! Setting up ox-hugo was very easy, and I did. I have the org file and corresponding page. Superscripts and latex blocks work perfectly.

Kudos to your ox-hugo project.

1 Like