In my previous post I guided you through how to use Hugo to make a site to deploy on GitHub. In this post I will show you how to go deeper with your customisations, and what you need to do to get the results you want.
First you need to make a Hugo site to play with, and have Git and GitHub pages set up. This was all touched on in my previous techblog post. At the end of that post I gave a link to Jake Weisler’s wonderfully useful post on understanding the Hugo directory structure. As far as I can tell it’s a little outdated in places, so I’m going to write about my experience and observations customising my Hugo theme in the hopes that is will help someone else.
The first thing that you need to know is that you will be dealing with a lot of duplicate folder structures. But fear not, if you follow my guide you will be using only three duplicate structures. If you followed my guide in the previous page, you will now have:
- A site generated in your ‘output’ folder. We will use this to check what happens when you make changes in the other places. It doesn’t matter for generation and so put it on the right of your screen so you can use it as part of your checks.
- A ‘content’ folder that contains some metadata files for Hugo to convert into HTML. This may need a subdirectory for your posts to be organised into, depending on what your theme needs.
- A customised config file.
- A ‘theme’ folder containing all the other information used to generate your site.
What we are going to do at this point is pull all of the theme information out, and place it into more accessible folders. This will leave the relevant theme folders empty - this is fine, because all the information will still be available to Hugo automatically in its new locations. Additionally, you should have a backup copy of your themes in storage so that you can refer to the original files or copy them back over. However I recommend that from this point, you only work with the files in the new locations that I’ll specify. This will keep duplication to a minimum and so remove some of the confusion that can occur with cause and effect when using Hugo.
First, cut the ‘layouts’, ‘assets’, and ‘static’ folders from your theme, and put them in your site’s root directory (which contains your config file). ‘Layouts’ contains the html templates used to make your site. These should be structured as a mirror to your content folder - you will notice that failure to do that will mean that your content is not produced, or if it is, it may be produced using an undesired HTML template.
- The ‘partials’ directory holds prewritten HTML that is used to make insertions in other pages. It may also contain SVG files and other icons. It is useful to know that the ‘header.html’ file is often where other functionality is held, such as holding the references to which icons will be used for the site’s tab.
- The ‘_default’ directory holds backup data for page generation which is used in some cases as a first reference, and sometimes as a backup for missing files.
- Also in here are your 404 and homepage (index) layouts.
Your ‘static’ folder will hold all your images and other files that you want fed forward into your site without change.
Your ‘assets’ folder is the most useful for overall personalisation. It contains your CSS generation file, which you can change to produce style changes in your sheets. I haven’t much experience with this (or web dev in general) so I can’t guide you much with specific changes, but I can guide you a little bit through the likely structure of these files.
- In the Hermit theme, the ‘assets/scss’ folder holds ‘_predefined.css’, which defines the colours used in the rest of the CSS. I made changes here that carry forward to the rest of the style info - although I didn’t change the colours’ string names. I imagine this is not good practice but I wasn’t about to do a find and replace on all files present (and then possibly still miss some changes in the HTML). For my purposes this worked well enough.
- The main style info is contained in ‘style.css’. I can’t advise you here, getting into CSS is not my purpose, but anyone willing to go digging in their file and google a few things can figure it out.
There should also be a js folder containing your site’s javascript. Again this is not a specialty of mine, but if you want to find yours, you should find it there.
I’m going to finish there and I hope that anyone who finds this has found it useful!