Tonight I went to start a new project. I wasn’t going to be using an existing theme, just starting from scratch. I was disappointed that the output of hugo new site and even hugo new theme was basically blank.
Rather than bringing up other projects and copying-and-pasting to start my new one, I instead made a skeleton theme. It’s basically what I wish happened from hugo new theme.
Whether it reflects best practices, I’m not sure–I looked for something like this before I made it and didn’t immediately find anything promising. And I probably didn’t think of everything. So I’m sure there is some way in which it sucks. 
Feel free to let me know.
2 Likes
I have a super minimal repo here with the best practices that I can think of: Files · classless-css · hugo-mwe / Hugo MWE · GitLab
1 Like
I have few comments:
- You have a special
index.html that renders to the site’s home page. There’s nothing wrong in that. If you prefer, you can remove that file and have the list.html render the home page as well.
- If you need to do something specific only for your home page, you can nest that inside
{{ if .IsHome }} in the _default/list.html.
- I like that you have defined the blocks as per basic HTML5 semantics: header, main and footer.
- But I am not sure if you need to define partials
header.html and footer.html. You can always override those blocks directly in single.html, list.html and other layout files.
- You are defining the
header block in baseof.html, but then are defining the header element the main block in list.html (and there are many similar inconsistencies).
- May be you can consistently use the
header block for only the main header element of the page (list, single, any!), main block for only the main element, and so on.
- In your
resource.html partial, if you are using assets/ for css and js files, there won’t be a need to clutter with the fetching of css/js from static/ as well.
- If this is your skeleton, you can be strict/consistent… that you either use assets/ or static/ for css and js.
Finally, I always like to check that my sites validate successfully with 0 warnings on https://html5.validator.nu/ (I have few warnings on my site, which I need to fix) Now fixed.
1 Like
The HTML <main> element is to be used once per page. Not <header> and <footer>; those are also used for sections, and can appear multiple times in a document. They don’t directly map to the Hugo template blocks.
I added the fallback to static in resource.html because I first made it for a project with stuff dumped in the static directory (which I eventually moved all of). I kept it here since I’m releasing it publicly and some people might prefer to use static.
Edit: I do see what you mean about, like, list.html ending up with a header for the site title and again for the page title. That’s probably not ideal.
1 Like
OK, at least for my use cases, I don’t see how header and footer partials can be reused for all: page header/footer and section headers/footers.
I only use them for page header/footer. Perhaps their existence as partials is confusing? I think I mostly use them so baseof doesn’t get cluttered but that’s probably not a good reason.
Don’t worry. It’s all subjective. Everyone’s code organization styles are different. I prefer to minimize the number of files and use less partials if possible… especially if otherwise I am ending up with tiny files will mostly go unmodified for a long time.
I’ve removed them. Nothing stopping me from factoring things out into partials as and when necessary.
Just got rid of my index.html file after learning about this! Wow!
Though not explicitly required if the direct descendant of the root element, as it’s inferred, I sometimes use the old-skool role attribute to make it clear, e.g:
<header role=banner>
As you rightly say, a header or footer element can also appear in other page elements, e.g which is why it would be unwise to hang styles directly from those named elements, imo.