Recommended Practices when building themes

Hey Folks, I’m working on converting my personal blog/podcast site into a reusable hugo theme for content creators.

This is a work in process, and really only started the refactoring into a reusable template yesterday. I have a few questions, and would love to get insights from the community -

  • Are there any recommended ‘site architectures’ e.g. where to store images for a certain page (blog post, episode page, etc.)? For my own site, I’ve been storing them directly in /static/img and have a folder structure there. From research, I’ve realised I could (and maybe should?) have stored these as a page bundle. Would this be a better way to go?
  • Are there any good tools to include as part of a CI/CD pipeline? I’m using GitHub Actions and have several pieces in there already (e.g. Checking for Accessibility, SEO, Building across different versions of Hugo and Node [for my dependencies in npm]). Are there any other good tips from a Static Web App / Hugo perspective?
  • Are there any ways to generate the ‘base required’ files for a site? For example, I may have a blog section, and need an for customising titles/descriptions. Similar for episodes, etc. Or, would the best approach be to have a subfolder e.g. baseSite?
  • If you have any other tips, would love to hear them! I’m going to be optimising the code in my hugo-creator repo, as I’m sure there’s plenty that I can re-work. If anyone’s looking to contribute into a theme, I’m happy to accept contributions and help others learn as well. This community has been great to me, so I’m always looking for ways that I can give back :slight_smile:


  1. Pagebundle. Yes. Nothing more to say. One folder to rule everything on a page.
  2. Sure, but that is going to be very specific. I would not build across different Hugo versions. If your theme works in the latest version of Hugo it’s good. Any earlier version… well… it’s an earlier version… Checking for accessibility/HTML errors/etc… do deploy to a Netlify site and test regularly (on deploy or on a tag or on push).
  3. Not sure if I misunderstand you but we call that Archetypes here :slight_smile: Create post types (sections) and add everything in a (see point 1) page bundle archetype (a folder with an and all files you need in every page bundle).
  4. Try to get some “dummy users” for your theme. You are “married” to your theme and won’t see the smaller issues that might come up because they seem obvious to you. Someone completely out of your mindset will make you lots of work, but you end up having a better theme.

And if something seems “hacky” to you it probably is and asking for an opinion here might help point you the right way. But don’t collect questions into one post. One post per issue :wink:

1 Like

Oh, and “documentation, documentation, documentation”. Especially if you have special features that require more setup.

1 Like

Thanks! And point taken on separate posts for separate issues :slight_smile:

Just to expand on the Archetypes piece, assume that I’m a user who’s brand new to Hugo and setting up a site for the first time.

Completely understand that we can use Archetypes to generate individual pieces of content within a section (e.g. blog/hello-world/, episode/episode-1/, etc.), and those could either be a page-based archetype, or a directory based archetype.

But, what if there is a need to have Branch bundles at the section level (e.g. blog/, episode/ I don’t think Archetypes would solve that - would they?

Not sure if I understand that correctly, so bear with me if I repeat things you already know: You create content via hugo new. If your new content is in a section that has it’s own archetype then the archetypes format is used (either file or directory), if not, _default archetype is used.

Then, and that seems to be what you are looking for, you can call hugo new --kind whatever path/to/new/content and hugo will look for the archetype whatever and use that setup.

But how often do you create specific section root content files? Maybe it’s best to document it somehow in the default archetype what to do with its frontmatter.