Welcome, this is my debut post on my new personal blog. I’m launching this site in the midst of the COVID-19 lockdown in New Zealand. Like many others in a similar situation, I am very restricted in the human contact I have, and have an overwhelming amount of free time. As a result, I will use this blog as an outlet for some of my ideas and projects for others to hopefully enjoy.
First up will be something a bit boring and meta, the making of this blog. The site project based on the static site builder Hugo, and I am using Google Cloud Platform for source control, build pipelines, and hosting.
I didn’t bother installing Hugo on my local windows machine (I don’t fancy installing ruby and various package managers), so instead I’m using the klakegg/hugo docker image.
As I author my source files in the asciidoc format, I am using the asciidoc docker image tag.
In order to create a new site, simply run the following in Windows cmd:
docker run --rm -it -v %cd%:/src klakegg/hugo:asciidoctor new site mysiteThis will create a new project folder called mysite with the structure that Hugo expects.
Next up is adding a theme, I chose the Hugo Notepadium theme from the official theme website.
Getting the theme to work is very simple.
First navigate to the mysite folder (the remaining commands should be run from this directory, unless otherwise stated), and make sure you have initialized a git repository with git init.
Then, add the theme as a submodule:
git submodule add https://github.com/cntrump/hugo-notepadium.git themes/hugo-notepadiumThis will download the theme into the themes/hugo-notepadium subfolder.
As it is linked to the source git repo, it is possible to update to the author’s future enhancements by navigating to that subfolder and running git pull.
Finally, in order to enable the theme, simply add in to the project config:
theme = "hugo-notepadium"And… you’re all set! But wait, first you need some content! To add a post in the asciidoc format, run the following:
docker run --rm -it -v %cd%:/src -p 1313:1313 klakegg/hugo:asciidoctor new posts/mypostname.adocOf course, replace mypostname with whatever you want the name of your post to be, and change the extension from adoc to md if you prefer Markdown.
Personally, I name my post names in the format 001-Hello.adoc - the numbering allowing me to display the files in an order I prefer.
The result of this command will generate a file in the content/posts/ directory with contents like so:
---
title: "Mypostname"
date: 2020-04-12T06:19:46Z
draft: true
---You can then append your actual content at the bottom. At this point, you’re all ready to test out your site! Simply run hugo’s built-in server:
docker run --rm -it -v %cd%:/src -p 1313:1313 klakegg/hugo:asciidoctor server -DNote that the -D flag shows draft posts.
You can stop a post being classed as a draft by removing the draft: true line from the header of the post.
Once this is done, you should be able to see your site by pointing your browser to http://localhost:1313/. The server supports live reloading so changes to your project should be reflected in the site immediately! This makes it great for local development and testing.
Success! You can build the website locally using the following command:
docker run --rm -it -v %cd%:/src -v %cd%/public:/target -p 1313:1313 klakegg/hugo:asciidoctor -DA subdirectory named public should appear which will contain the generated static website.
If you wish, you can upload this to the static folder of your favorite web server and be done with it.
However, leaving it at this would mean carrying out a manual process each time you want to add a new blog post.
Now, you could automate the build and upload into a script, but that would require access to Hugo - and whatever upload tool you use - for each device you edit your website on.
The proper (read: over-engineered) way of solving this is to trigger a cloud-based build and upload whenever code is pushed to the repository’s master branch.
Stay tuned for Part 2!