Syntax-Highlighting

Right, so you want to draw diagrams. You’ve tried pasting screenshots from some clunky web app into your blog post and it’s a nightmare. The text is blurry, the colors are wrong, and heaven forbid you need to update it later. You’re a developer, not a graphic designer. Your tools should work for you. This is where Mermaid swoops in like a superhero in a terribly drawn cape. It’s a JavaScript-based diagramming tool that lets you create everything from flowcharts to sequence diagrams using nothing but text. It’s code, for pictures. And Hugo, being the opinionated genius it is, has first-class support for it through its default Markdown renderer, Goldmark.

Right, let’s talk about letting Hugo get its hands dirty with raw HTML. By default, Goldmark, Hugo’s Markdown processor, is a bit of a neat freak. It sees your <div> or <script> tag and immediately sanitizes it into oblivion. This is, generally speaking, a fantastic idea. It prevents a whole universe of cross-site scripting (XSS) attacks and keeps your site from accidentally turning into a mess of malformed tags. But sometimes, you need that control. Maybe you’re embedding a complex interactive chart from a third party, or you’ve built a custom CSS widget that just needs a specific HTML structure. This is where the ominously named unsafe setting comes in. Don’t let the name scare you; it’s not inherently evil. It’s just Hugo being very clear with you: “You’re turning off the safety rails. Don’t blame me if you drive off the cliff.”

Right, let’s talk math. You’ve probably been there: you’re writing a beautiful post about the elegant simplicity of the Lorenz attractor or the statistical sorcery behind a p-value, and you need to render an equation. Not a sad little screenshot from a word processor, but real, honest-to-goodness math that looks sharp at any zoom level. Hugo, in its infinite wisdom, doesn’t do this natively. The underlying Markdown renderer, Goldmark, is fantastic for text but throws its hands up at a block of LaTeX like it’s an ancient cursed script. And honestly, that’s fair. LaTeX is a kind of ancient cursed script. So we have to bring in the big guns: either KaTeX or MathJax. Both are excellent JavaScript libraries that parse LaTeX syntax and turn it into beautiful math on your page. The choice between them is one of philosophy and performance.

Right, let’s talk about the fun stuff—the little syntactic sugar cubes that Hugo’s default Markdown engine, Goldmark, lets you drop into your content to make it less of a plain-text snoozefest. We’re talking tables, checkboxes, redacted thoughts, and the academic’s favorite: footnotes. These aren’t part of core CommonMark, so thank the Hugo and Goldmark teams for not leaving us in the 2014-era of Markdown. Tables: Where Alignment Goes to Die Let’s be honest: writing tables in Markdown is a bit like assembling IKEA furniture with vague pictograms. It’s functional, but you’ll never feel good about it. The syntax is downright silly, relying on colons and dashes to define alignment.

Right, so you’ve got some code you want to show off, and you want it to look good. Hugo’s highlight shortcode is your first-class ticket out of bland, unstyled code blocks. It’s the difference between a mumbled explanation and pointing at a diagram with a laser pointer. But here’s the kicker: its behavior depends entirely on which Markdown renderer you’ve told Hugo to use. If you’re on the default, Goldmark (and you probably are), you get to play with a slightly different, albeit more powerful, set of rules.

Right, let’s talk about making your code blocks look less like a sad notepad.exe session and more like you opened it in a proper IDE. Hugo, in its infinite wisdom, doesn’t do this itself. It outsources the job to a library called Chroma. This is a good thing. Chroma is excellent. It’s written in Go, it’s fast, and it supports a staggering number of languages. Your job is to tell Chroma exactly what you want.

Right, so you’ve decided to use Markdown. Good choice. It’s the closest thing we have to a universal authoring format for the web. But Markdown isn’t a single, monolithic standard; it’s a family of dialects. Hugo, in its infinite wisdom (and for very good reasons), uses an implementation called Goldmark. Think of it as CommonMark—the sane, standardized specification—with a bunch of very useful, and occasionally bizarre, party tricks bolted on.

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.