How Hugo themes work

Hugo is really two stacked things:

1. The plumbing: content model, Markdown/org rendering, taxonomies, pagination, RSS/sitemap/robots (these are internal Hugo templates, free), the asset pipeline, fast rebuilds, and (in my case) the ox-hugo bridge from org-mode.
2. The theme: just layout templates. The style.

Instead of creating a true custom theme, which is a full package that could be shared on Hugo’s theme page (and would need to be indefinitely maintained and guaranteed portable), I’m taking a different route, and I’m explaining it here in case someone (you) might want to adopt the same plan for your own site.

This current “theme”

My plan hinges on one aspect of Hugo’s functionality: the local project-root layouts/ overrides the theme’s layouts/. This means you can write your own templates one file at a time while the theme stays installed, and each file silently takes over that page type. You also don’t need a template for every page type - Hugo has a fallback chain, and the minimal complete set is just _default/baseof.html, _default/single.html, _default/list.html, index.html, and 404.html.

Start with those, and then each other component of the layout can be replaced, one by one, tweaking to the result you want on your own site. Eventually, when every single thing has been replaced, you can just delete the entire theme line from hugo.toml. At that point, everything is coming from your own collection of layout files, and they form your custom theme.

A true theme is more than just layouts, it can inject assets/, static/, default params, i18n/, and archetypes/. Those still merge even when the layouts are fully shadowed. So if you don’t want those from the theme, you will need to do the full removal, deleting that theme line from hugo.toml. And to get there, you need your own templates covering every page type your site actually produces - not necessarily every template the theme ships, since it probably includes layouts for page types you’ll never use.

So here’s my basic workflow in creating this current “theme”:

Start with a basic theme. The more complete the theme, the more of your site’s behavior hides inside the theme’s files instead of yours - so when you finally remove it, you’ll discover it was doing more than you realized. I started with hugo-bearcub. I tweaked each aspect of the theme using my own file in layouts/ until I no longer needed that theme, and I deleted the theme = 'hugo-bearcub' line in hugo.toml.

You might expect at least one surprise when you do. In my case the theme had been quietly supplying robots.txt - with a Sitemap: line in it - and Hugo’s built-in version has neither. Nothing looked broken, because nothing looked like anything; it was a file I’d never written and didn’t know I was relying on. Part of the argument for doing the removal instead of just shadowing the layouts and calling it done.

Then I browsed around Hugo’s theme gallery for the more feature-rich themes, looking for specific things I’d want to incorporate into my own site. When I found something, I edited/created a file in my own project-root layouts/ directory, and magically that feature/component shows up in my own site.

Hope that’s helpful for anyone wanting to get a custom look on their Hugo site.

Eventually, I expect much of the usefulness of this site will be found in utilities and projects in the subdomains. Because this is hosted on GitHub Pages, those will need to run on other servers. For now this is just the static base site. I have the domain, may as well finally use it.

I’m also a big fan of simplicity in technology, so I don’t mind a simple static site. Filling it up with interesting content is the real challenge.

Technical details

Here’s a description of the technical side of the site, for anyone interested:

The stack is Emacs -> ox-hugo -> Hugo -> Git -> GitHub Pages. If you know what those are, then you already know what’s coming.

I write the site, including these posts, with Emacs in Org mode format. When I’m done making changes, I can press an Emacs key combination and the ox-hugo package compiles the file into markdown for Hugo. The directory is a git repository, and when I commit and push my changes GitHub Actions automatically updates the page on GitHub Pages.

This makes writing new content an extremely simple process, basically just editing a plain text file. Each Org heading is its own post, subheadings become sections. Marking the heading DONE will include the post in the next export. I can commit with magit, so I never even have to leave Emacs. The Org tree of this current post looks like this:

* DONE A new website :hugo:emacs:org:web:@Technology:
  CLOSED: [2026-07-19 Sun 00:23]
  :PROPERTIES: :EXPORT_FILE_NAME: a-new-website :EXPORT_DESCRIPTION:
  What am I doing here?  :END: (content) ** Technical details
  (content) ** Blog (content)

So guess what comes next?

Blog

I generally don’t use social media, I may have accounts but I never check them. If I have anything interesting to write, I now have this blog. This will be a good place to put the things I think or learn about computers/data/AI/etc. I may be unemployed, but technology is my profession and so that’s what I will focus on. I haven’t decided how far posts may occasionally stray from technology, we’ll find out as time goes on. In any case, this is an informal personal site. It won’t be the kind of content you might find in a newsletter on any specific topic.