Greetings, this isn’t the first time, probably not the last time where I start writing a blog about things I’m learning about or aspects that I’m interested in, but hopefully this one will last longer than all the rest.

Have you ever been told you must do X or you need to do Y and do it begrugenly, that’s pretty much how I felt about all the previous attempts of creating a blog felt like to me, and in those situations I don’t keep things going for very long… So fingers cross I can keep this going.

Though I’ll write another blog post in the general section, this one is meant to be more of the technical aspect of it all!

So just to run you through the various technologies that I’m using to host this (obviously some factors will be left out)

Technologies being used:

  • Hugo - This is for the static website generator.
  • Github - Code Repository for code management, version control and deployment to my webserver
  • Raspberry Pi 4 and Nginx - This is where my blog is currently being hosted, May move it to the cloud at some point, but this is a playground for now.

Hugo Who? Why Hugo?

There were a number of difficulties that came with this decision, though I am determined to work through them (and I’ll post follow up posts when I finally overcome them), one of the troubles I’m having is with nested taxonomies, or nested categories that you might easily get with something like Wordpress or other website tooling. But for me, creating this blog using Hugo is meant to be more of a learning experience to allow me to improve my skills using it for coming up with ideas for the Tokonatsu Website that I help look after from time to time. (For those that don’t know, Tokonatsu is epic and I have a blog post covering just that! You can find that here )

Just writing that previous paragraph, I’ve ended up learning how to embed links into the text! Lets see what else I can muster throughout this.

But getting back on track, my choice is to use Hugo, Partly because of it’s feature set (it says it’s lightweight and fast, and so far I can’t complain at how fast getting this up and ready was) as well as to improve my skills for other developments such as Toko’s website! (There is a couple of additional aspects I wouldn’t mind borrowing from it to improve this site, but little steps)

So why Github?

Github is a fairly obvious platform to use, although Gitlab is also a close second (other options were to self host a private instance, but with free Private Repositories and Action allowances Github or Gitlab would have won that fight) the main reason I went with Github over Gitlab is purely because I have all my other repositories on Github, Other coding projects I work on are hosted on Github, so why spend time hoping between different platforms if I don’t need too! Though I won’t say no to working on Gitlab if there were exciting projects going on over there (I have no doubt there is, just nothing that has drawn me in just yet)

Where are we going to see this?

and Finally my choice of Hosting Platform, a Simple Raspberry Pi 4 and Nginx, yes I could deploy a Hugo site in various locations, AWS, Google Cloud Platform, Azure, or even in Github Pages it’s self, all of these are very valid options, and it’s not like the cost of this blog will be horrendous to do within the Cloud Platforms, but I wanted to give my self a reason to write another blog post in the future when I decide to Migrate… I mean that would be one reason that’s for sure. Another is that I like to tinker and see what goes on in the backgrounds, and self hosting things can be fun at times. But no doubt sometime in the future I will be moving this to a cloud provider (Who will I choose, find out later I guess, the answer might surprise you. )

On to the setup!

So getting started is actually a very simple process, firstly need to make sure you have Hugo and Git installed on your machines (This can be Windows, Linux or MacOS) the best way to do this is to follow the instructions on the Hugo and GitHub / Gitlab websites as these will have the latest instructions on what to do. (This prevents this blog post from going out of date) at the time of me writing this, the current Hugo Version is v0.117.0 for extended windows.

Because there are times where I’m away from home, I make sure to have the same setup on my Macbook as well, so I can make sure to check how the posts look before publishing them.

Once the requirements have been installed, I then followed the quick-start guide on the Hugo Website to create a basic website. (I was also using the Tokonatsu Website as a basis for some aspects as well, but due to it using an older version of Hugo some things are a little different, such as the config.[toml / yaml / json] file has been renamed to hugo.[toml / yaml / json] as it stands you can still use config, but chances are in the future you will not be able to). As you then do spend a good 20 / 30 minutes looking in the Theme directory to work out what style theme would suit you and what you’re trying to go for ~ I ended up going with the m10c theme.

You can install themes fairly easily, if you go to the theme page it will mention a git clone url. for the example of the m10c theme I’m using it says: git clone https://github.com/vaga/hugo-theme-m10c.git themes/m10c though this wasn’t the way I’ve got it included within my project. Instead, I’ve got it included as a Git Submodule

To include it as a Git Submodule, we first need to turn the directory into a Git Repository. In this instance all we need to do is go within a Command Prompt, or Terminal Window, navigate to the folder where you’ve created your basic site and then use the command git init and this turns your project folder into a git repository. (This is needed for a later step)

Once done you can then use the following command to include the new theme: git submodule add https://github.com/vaga/hugo-theme-m10c.git themes/m10c

This will then include the theme into your themes folder, finally to use the theme you just need to add the line

theme = 'm10c'

inside of your hugo.[toml / yaml / json] file.

Once the basics were up and running and then using the hugo server -D command to get it running locally and it working as intended it was then we can start thinking of commiting our changes and posting them to Github (or another git platform)

So head on over to Github (if you don’t have an account, register it’s Free!) and create a new repository. Name the repository how ever you want, but I tend to name it relative to what I’m working on, so for example this repository for this blog is called adam-hay-blog, you can then set the repository to be public or private, I tend to keep close personal stuff private, but anything fun that I think anyone can use as public. Normally I would say to include a Readme File and a .gitignore file but because we already have everything ready to go it may cause some conflicts, though this doesn’t stop us from adding these files in the future (spoiler, we end up creating a .gitignore file before pushing the repository to github.) and then create repository. This will then take you to a screen with lots of information.

Unless you have a SSH Key (the process of setting one of these up can found on the Github Website, but I won’t be covering it here) you will need to select the HTTPS option within the Quick Setup. We’ll be following the ...or push an existing repository from the command line set of commands.

So we head on back to our project folder, we’ll quickly add the .gitignore file as mentioned previously, this will prevent us from commiting or pushing anything we don’t intend.

This is an example of the .gitignore that I use:

# Do not upload the build folder
public

# DS_Store Files Ignore
.DS_Store

# Static CMS hold (temp)
static/admin-cms

# Any ENV files that might be hidden away
.env

# Adding the .hugo_build.lock file which is normally empty
.hugo_build.lock

once this has been created and saved in the base directory of your project, we can then follow those steps mentioned earlier within the command prompt.

The commands are as follows, though yours will be different to mine:

git remote add origin https://github.com/Yamakiroshi/blog-post-test.git
git add .
git commit -M 'first commit'
git branch -M main
git push -u origin main

What this is basically doing is linking your local Repository to the one located within Github.

You are then adding all the files within the Local Repository ready for commiting.

You are the readying the files to be sent / pushed over to Github

Making sure the current branch is named main

and finally pushing everything over to github.

If you then refresh Github you should then be able to see all your files there, and thus you have started your first steps of getting your blog ready to be deployed to an external location!

Due to the length of post, I will be moving the steps to deploy this Hugo Blog in a Part 2, so keep your eyes open for that!

If you have any questions or would like to know more, feel free to get in touch. My socials are listed in the menu bar to the side!