Fixing Reference Display Issues with ox-hugo

The Problem

I was trying to use Org Cite Citations and the following code to display my references:

#+print_bibliography:

But only the “References” header showed up – the actual list of references was missing.

I checked the generated Markdown (.md) files in my content/ directory, and the reference list was there in HTML. However, when I looked at the final HTML files in the public/ directory, the references were gone.

This suggested the problem was happening during the Markdown-to-HTML conversion (the md -> html part of org -> md -> html). After some digging, I found an issue on GitHub about the same problem, which led me to the solution.

The Solution

Adding the following to your config.toml file will fix it:

[markup.goldmark.renderer]
  unsafe = true

In my case, I’m using YAML, so I configured it like this:

markup:
  goldmark:
    renderer:
      unsafe: true

Explanation

As described in Goldmark — ox-hugo - Org to Hugo exporter, starting with Hugo v0.60.0, the default Markdown parser was changed to Goldmark, which is CommonMark compliant. The previous default parser, Blackfriday, wasn’t spec-compliant and had a lot of bugs. It’s generally recommended to switch to Goldmark if you’re using ox-hugo, unless you have a very specific reason not to.

However, Goldmark/Hugo has some differences in how it parses Markdown compared to Blackfriday. One of these differences seems to be the issue I ran into – inline HTML not rendering correctly.

Enabling unsafe = true allows you to use inline HTML within your Markdown.