Hugo and this Site

I built this site using the Static Site Generator Hugo, and the Hermit theme by Track3.

Why a Static Site?

Static sites load once when accessed. This makes them cheap to serve. Services like Netifly and GitHub pages will serve your website for free. Additionally, because they lack dynamic elements (basically the ‘moving parts’ of a modern website), they don’t need updating for security reasons or otherwise. I can “fire-and-forget” with this setup. Additionally, as a new web dev (if you can even call me that), static sites probably represent the simplest route from knowing nothing to having a functioning site.

Why use Hugo?

Jekyll is the ‘default’ for GitHub pages but aside from GitHub’s guidance on Jekyll being more available, Hugo was no more difficult to use and much less difficult to install. In fact, my first choice - on the basis of a Slant comparison promising an active community - was Pelican. I was biased towards this choice because I’m a new programmer and I’m trying to focus on Python. Additionally, if possible, I want to present functioning Python code in my site. I don’t know yet if you can do that using Pelican, but in the meantime I have found PythonAnywhere, to which I can link from this site if I want to present running code, or if it is possible I can use Pelican later to generate the relevant pages. The first versions of this site were made using Pelican but I found the available information unsatisfactory and often out of date. I migrated to Hugo because looking further into comparison sites, it seemed like Hugo has a slight edge in speed. I don’t know whether it was an effect of my experience from learning Pelican but I found Hugo much easier, although still difficult enough as a new programmer, to get on with. Other SSGs include Gatsby, which looks good for sites like this, and NextJS, which looks good for commercial sites.

I didn’t want to use Wix and ilk:

I don’t care if it hurts, I wanna have control.

Why write this guide?

It’s partly a record for me, partly a writing exercise, partly trying to help others who might struggle like I did when coming in with no experience. Other guides will be more granular and this should be a supplement to those. Here I’ll try to stick to a readable recipe format that will produce results and leave the reader with a holistic understanding of what’s going on.

Disadvantages of this guide:

It’s written from memory by someone not dilligent at keeping notes (hence this blog, to motivate me).
It’s not paginated

Advantages of this guide:

It was writted by an inexperienced programmer (I know which points I struggled with most and can help you with them).
It is up-to-date as of June 10th 2020, where I found other guides to be outdated.
I try to use simple language to explain complicated things. I’m a native English speaker. I’m using a recipe-esque format and I’m keeping my former self/an ignorant hypthetical naive reader in mind.

How exactly did you go about making this site?

If you’re fully following along with this guide and want to use GitHub pages, you’ll need to have and know how to use Git and a GitHub account. To make and work on a test site for later deployment requires only Hugo itself.

First, I downloaded the appropriate Hugo binary from their website. This is where I made my first mistake - I downloaded the standard version for my system, but in fact I later found I needed the extended version. I recommend that you get the extended version, because it lets you rebuild CSS/SASS, which you will need for making and editing colour schemes. If you’re using Windows, you can install a Linux version to WSL, and I recommend this option if you have WSL set up - so long as you can get GitHub ssh-connected, which I haven’t managed yet, meaning I have to enter my password every time or run a separate terminal for git. It’s possible that I could run both Hugo (Windows install?) and Git from GitBash. But I don’t trust that method so I’m running everything from Powershell, which is easy enough. Note: I installed using Chocolatey, but this isn’t necessary or important for this guide.

Secondly, I wanted to make all the themes available so I could compare them and switch between them. You can skip this step if you want to save space. To do this on Windows, I recommend that you make a folder in your documents called ‘Hugo’. Hunting down any usable installation directory for Hugo (at least using Chocolatey) was relatively fruitless, and having the themes in the Hugo install folder will only make them more difficult to find. GitHub holds a massive repository of themes - simply git clone what you want into your Hugo folder, and now you have copies in storage, all updateable with a single command. Please be prepared for the git clone to take quite a long time if you choose to get all of them like I did. I nearly ctrl+c’d the process but it finished just as I was hovering over the keyboard.

Next, from your downloaded themes, you’ll want to choose one to work with. Fittingly, I liked the ‘Hermit’ theme by Track3 and used it to build this site. Copy (don’t cut and paste because you’ll want a clean copy in storage!) the folder of the theme you like and navigate to the folder where you want to make your site. (I did this in the documents/GitHub folder that the GitHub for Windows program left behind on my computer. I’m working on a more decentralised mindset (i.e. running Git in whatever folder necessary as it exists in my computer, rather than having a Git ‘section’. It’s a holdover from the ‘trying Git for the first time’ mindset)).

Once you’ve picked a location for your new site, open a command window in that location. This is Powershell if you’re using Windows - I installed on Windows rather than WSL, but I would use WSL if installing again (once I can solve that ssh problem). You can cd into the folder; I more often navigate in File Explorer and use the right-click context menu to open a Windows Terminal window there. Now with a command line open in the correct folder, run ‘hugo new site’. Answer the questions honestly and don’t worry too much about the answers, we’ll be going straight into the settings anyway. This will generate a bunch of files and folders with which you will become very familiar. Hopefully I can save you a little reading on that front.

For now, just copy the theme you want to use into the new directory ‘themes’. Now you’re ready to go. You can generate a test page at this point with the hugo new test.md command. The settings (front matter) in this page won’t be what you want them to at this point, but we’re about to change that.

What does Hugo do?

Hugo’s primary purpose is to make the HTML and CSS files that will make up your site. That’s not all it can do, but we will ignore the rest for now.

What input does Hugo take?

Hugo’s input comes from four places:

The ‘content’ folder, where you will store your written files. These files will be in the CommonMark Markdown format, which you can learn in a few minutes. If you can do all the tricks with text on Reddit, you’re already proficient in CommonMark*.
The ‘themes’ folder, which right now contains everything else, kindly provided by the creator of your theme. This includes a prototype site structure for Hugo to create your site with, HTML layouts, CSS stylesheets, images, icons, and more.
The config file, which is located at the root of your document, and will be written in YAML, TOML or JSON - simple and self-explanatory languages that you won’t need experience to work with.
The files and folders which you will use to customise your theme. These branch off from your root folder, and replicate files and folders in your ‘themes’ folder. These will be preferred over your theme’s settings but your theme will apply if nothing is found here. More on these later, for now let’s look at your config file.

Your config file

Hugo will have created this for you when you ran ‘new site’. However it will have the default info in it, which is unlikely to be compatible with your theme. So, you’ll need to dive into the documentation for the theme to find compatible settings. You’re likely to find these in the readme in the theme’s root folder, and another example in the theme’s example site if provided. Open these files (in a suitable text editor such as Sublime Text 3, Visual Studio Code, or NotePad++) and hold them to one side. Finally, open your own config file and get to work. I’ll provide mine, which is in TOML, as a third reference which might be useful:

baseURL = "https://darkhorsemechanisms.github.io./"
relativeURLs  = true
canonifyURLs  = false
languageCode = "en"
defaultContentLanguage = "en"
title = "DarkHorseMechanisms"
subtitle = "A place I share with you"
metadescription = "A home for all my projects"

newContentEditor = "C:/Program Files/Sublime Text 3/sublime_text.exe"

publishdir    = "./public"
contentDir    = "./content"
layoutsDir    = "./layouts"

theme = "hermit"
enableGitInfo = false
pygmentsCodefences  = true
pygmentsUseClasses  = true
rssLimit = 10  # Maximum number of items in the RSS feed.
copyright = "This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License." # This message is only used by the RSS template.
enableEmoji = true  # Shorthand emojis in content files - https://gohugo.io/functions/emojify/
# googleAnalytics = "UA-123-45"
# disqusShortname = "yourdiscussshortname"

buildDraft  = true
buildFuture = true
buildExpired = true


[author]
  name = "DarkHorseMechanisms"

[blackfriday]
  # hrefTargetBlank = true
  # noreferrerLinks = true
  # nofollowLinks = true


[taxonomies]
  tag = "tags"
  # Categories are disabled by default.

[params]
  dateform        = "Mon, 02 Jan 2006 15:04:05 MST"
  dateformShort   = "2 Jan"
  dateformNum     = "2006-01-02"
  dateformNumTime = "2006-01-02 15:04 -0700"

  # Metadata mostly used in document's head
  # description = ""
  # images = [""]
  themeColor = "#000000" # uses RGB codes?

  homeSubtitle = ""
  footerCopyright = ' &#183; <a href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank" rel="noopener">CC BY-NC 4.0</a>'
  bgImg = "hojackborseman2.png"  # Homepage background-image URL

  # Prefix of link to the git commit detail page. GitInfo must be enabled.
  # gitUrl = "https://github.com/DarkHorseMechanisms/"

  # Toggling this option needs to rebuild SCSS, requires Hugo extended version
  justifyContent = false  # Set "text-align: justify" to `.content`.

  relatedPosts = false  # Add a related content section to all single posts page

  code_copy_button = true # Turn on/off the code-copy-button for code-fields
  
  # Add custom css
  # customCSS = ["./css/style.min.1af9598a67c2b0d68e66dfdd87aa5011a434a38bc7a6991709217bbd786ca823.css"]

  # Social Icons
  # Check https://github.com/Track3/hermit#social-icons for more info.
  [[params.social]]
    name = "twitter"
    url = "https://twitter.com/DarkMechanisms"

  # [[params.social]]
  #  name  = "youtube"
  #  url   = "https://www.youtube.com/channel/UCGGxnGLPnSjlsQjufz1IYQQ/featured"

  [[params.social]]
    name  = "github"
    url   = "https://github.com/DarkHorseMechanisms"

  [[params.social]]
    name  = "reddit"
    url   = "https://reddit.com/u/DarkHorseMechanisms"

[menu]

  [[menu.main]]
    name    = "TechBlog"
    url     = "posts/techblog"
    weight  = 10

  [[menu.main]]
    name    = "Links"
    url     = "/posts/links"
    weight  = 15

  [[menu.main]]
    name    = "About"
    url     = "posts/about/"
    weight  = 20

Note: I may have messed a few of these up, in particular I’m suspicious of the date and time fields.

I’d start by copying in one of your example files, then comparing it to the other and importing any (I mean any, even if you comment them out for the time being) setting that you think you might need. The TOML, YAML and JSON formats are simple enough to work with. Once you have a config file that looks like it will do what you want, you should save a backup copy (it’s simpler not to init git here until git is set up in your /public directory.)

Everything before [params] is a Hugo builtin setting and won’t* break your theme. Everything after [params] is used by your theme’s files. Once you have things personalised to your liking (‘theme’ must match the exact name of the folder holding your theme - for myself I had to rename ‘hugo-hermit’ folder to just ‘hermit’) you should definitely test run a site by following these steps.

Make a new page (hugo new filename.md) if you haven’t already, and make sure it’s in content or in content/folder where ‘folder’ equals the name of the directory that Hugo is expecting to find. The file will contain some ‘front matter’ at the top, and the rest will be in markdown. You can type plain text in the lower part of this file without much issue if you don’t know markdown yet, just don’t use any special characters for now (*, \, _ etc). This file will be converted to HTML by Hugo, but you might first need to change the ‘draft’ field to false in the front matter or set buildDraft to true in your config.
From the root folder, run the ‘hugo serve -v’ command. This will verbosely create a temporary version of your site to view locally, at the browser address provided when the command has run. Mine deploys to http://localhost:1313/.
If an error occurs, check various things - you might not have saved files in your open text editors so the changes won’t be read by Hugo. You might need to change some settings, or update your version of the theme (this is unlikely if you got it from git but it happened to me when I downloaded from the theme homepage). If no errors occur, have a look at your site and browse around. Congratulations!

You can now deploy to GitHub Pages. From the root directory (where your config file is), run the ‘hugo’ command. Navigate to /public (using the cd ./p* command to save time) and run git init. Next you’ll need a repo in your GitHub called ‘yourusername’.github.io. and to go into settings in that repo to activate it as a website. Finally, push the local repo holding your site into that remote GitHub repo. Your site will shortly be available at yourusername.github.io.

Next we will talk about getting more granular than the config file, when it comes to customising your website. This will involve looking at the folders making up your site in more detail. I am indebted to Jake Weisler for much of my understanding of this; his discussion can be found here.

This post is long enough so I’m starting a second one titled Hugo Site Customisation - Beyond the Config File.