Right, let’s talk about Goldmark. If you’ve used Hugo for more than five minutes, you’ve used Goldmark, whether you knew it or not. It became the default Markdown renderer back in Hugo 0.60, and it was a godsend. We were all stuck with the old Blackfriday renderer before that, which was… fine, I guess, if you enjoyed the technical equivalent of a dial-up modem. Blackfriday was slow, its feature set was frozen in amber, and it was about as standards-compliant as a pirate’s code. Goldmark, in contrast, is a modern, CommonMark-compliant powerhouse written in Go. It’s fast, it’s strict (in a good way), and it gives us a ton of knobs to turn.

The “strict” part is the first thing you’ll probably notice. CommonMark is a well-specified standard, which means Goldmark isn’t going to let you get away with the sloppy Markdown habits you might have cultivated over the years. That dangling unclosed asterisk that *almost made something italic? Goldmark leaves it as plain text. That indented code block that’s off by one space? Nope. This isn’t Goldmark being difficult; it’s being correct. It forces you to write clean, portable Markdown that will render the same way everywhere, and you should thank it for that.

Configuring Goldmark: Unleashing the Beast

Out of the box, Hugo ships with a sensible default Goldmark configuration. But the real fun begins when you crack open your hugo.toml (or .yaml, or .json—I don’t judge) and dive into the [markup.goldmark] section. This is where you enable the good stuff.

Let’s say you want to use footnotes, because you’re fancy. You need to explicitly enable them. Want to toss in some definition lists or a <mark> tag? Same deal. Here’s a robust configuration that turns on almost every extended feature:

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
      typographer = true
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xHTML = false

Let’s talk about the two most important settings here: unsafe and typographer.

unsafe = false is the default, and you should probably leave it that way. This setting controls whether Goldmark will allow raw HTML in your Markdown. When unsafe is false, any HTML you write will be rendered as literal text, escaped so it shows up on the page. This is a crucial security feature, especially if you’re processing user-generated content. It prevents cross-site scripting (XSS) attacks. Turn it to true only if you fully trust the source of your content and you absolutely need to embed raw HTML. You’ve been warned.

The typographer option is just delightful. It automatically replaces dumb quotes with “smart quotes,” double hyphens (--) with an em dash (—), and so on. It makes your text look professionally typeset with zero effort. Why anyone would turn this off is beyond me.

The Party Tricks: Footnotes, Task Lists, and More

Enabling those extensions is just the start. Now you get to use them.

Footnotes are a personal favorite. They’re perfect for asides, citations, and dad jokes.

Here is a sentence that needs a clarification.[^1]

[^1]: This is the clarification. See? Neat and tidy.

Task lists are incredibly useful for documentation or project notes.

- [x] Install Hugo
- [x] Figure out Goldmark configuration
- [ ] Write that novel

Definition lists are sadly underused. They’re perfect for glossaries or metadata-style pairs.

Term 1
: Definition 1

Term 2 With *inline markup*
: Definition 2

The Rough Edges and Pitfalls

Now, let’s be honest. It’s not all perfect. Goldmark’s strictness can be a pain when you’re migrating an old site with decades of crusty, non-compliant Markdown. Be prepared to do a lot of find-and-replace.

The most common “gotcha” I see is with code fences. Goldmark is picky. The closing fence must be at least as long as the opening fence. If you open with three backticks, you can close with three or more. But if you open with four, you cannot close with three. It will break spectacularly, and the rest of your page might not render. Just be consistent. Use three and move on with your life.

Another edge case: Goldmark’s linkify extension is brilliant—it turns raw URLs like https://example.com into links automatically. But it can be too clever. I’ve seen it accidentally mangle code comments or pre-formatted text that contained what looked like a URL. If this happens, your best bet is to just disable linkify and be more explicit with your links.

Ultimately, Goldmark is one of Hugo’s best features. It takes the boring, predictable world of Markdown and makes it both more powerful and more robust. It’s the foundation upon which your content is built, so taking the time to understand it is never wasted. Now go configure your hugo.toml and make your Markdown work for you, for a change.