Output-Formats

Right, so you’ve built this beautiful, content-rich site. I’m proud of you. But now your readers are going to want to find things. Scrolling through pages is for chumps and people who still use AOL dial-up. We’re building a search index. This isn’t about slapping a Google Custom Search bar on there and calling it a day. That’s lazy, and it hands over your user’s data to a third party. We’re going to build our own client-side search. It’s faster, it’s private, and it gives you total control. The two heavy hitters in this space are Lunr.js and Pagefind. I’ll show you both because they represent two very different, very valid philosophies.

Right, AMP. Let’s have a talk. AMP, or Accelerated Mobile Pages, is Google’s well-intentioned but often controversial project to make the web faster. The idea is simple: you create a version of your page that follows a very strict, stripped-down set of HTML and CSS rules. In return, Google caches it on their servers and serves it from their own domain (usually google.com/amp/...), which makes it load near-instantly on mobile devices. It’s a classic deal with the devil: you get ludicrous speed and potential SEO benefits (it used to be a requirement for the “Top Stories” carousel), but you sacrifice a lot of control over your own content and design.

Right, so you want an RSS feed. Not just any feed, but your feed. One that doesn’t look like it was generated by a bored robot in 2003. Good. RSS is a cranky old standard, but it’s far from dead. It’s the un-opinionated, user-centric backbone of the independent web that refuses to die, and customizing it is a small act of rebellion. Let’s make yours brilliant. The core truth you must accept is that an RSS feed is just XML. Not scary, magical XML, but a specific, documented XML format. Your job is to generate that XML correctly. Most frameworks have some built-in RSS generator, and they’re usually… fine. But “fine” is for cowards. We’re going to bend it to our will.

Right, so you want to build a JSON API with Hugo. Good choice. It’s a shockingly capable static API engine, and it saves you from having to maintain a separate database and server just to serve some structured data. We’re going to move beyond the basic json output format and build something you’d actually be happy to have a frontend app consume. First, let’s address the elephant in the room: Hugo is a static site generator. It builds files. An API typically implies dynamic requests. The key here is that we’re building a static API. All the possible data responses are pre-rendered as JSON files at build time. This is brilliant for read-only data (blog posts, product catalogs, documentation) because it’s insanely fast, secure, and cheap to host. It’s a terrible idea for anything that needs real-time, user-specific data. Don’t try to build a stock trading platform with this.

Right, so you’ve got your content. It’s beautiful. But now you need to get it out into the world in different shapes. You don’t want to just slap an .xml extension on a page and call it a day. You want /articles/my-great-post to be able to serve up its glorious HTML self, a clean JSON representation for some headless CMS nonsense, and a tidy RSS item for the three people (hi, mom!) still using feed readers. The key to this magic trick is telling your static site generator which page kinds should be able to produce which output formats. It’s about association, and Hugo handles this with a concept so simple you’ll wonder why other SSGs make it feel like rocket surgery.

Right, so you’re tired of the same old HTML and want to spit out something a bit more structured, like JSON for an API, or RSS for a feed, or maybe even something like AMP for Google’s fleeting whims. Good news: Hugo’s custom output formats are your new best friend. This is where Hugo stops being just a website generator and starts being a proper content engine. The bad news? The configuration is a bit… idiosyncratic. We’ll get to that.

Right, let’s talk about the freebies. Hugo doesn’t make you build everything from scratch. It comes packing a set of built-in output formats that cover about 90% of what a typical website needs to do. These aren’t just afterthoughts; they’re core to its philosophy of being a full-fledged web engine, not just a fancy blog generator. We’ll get to the cool custom ones later, but first, you need to understand the tools already in your belt. The big ones are HTML, RSS, JSON, and CSV. But we’ll also touch on the two special-purpose ones: robots.txt and sitemap.xml.