Websites usually do not have a ‘how it was built’ page.

But for this one, I felt compelled to have one. I would not have been able to build this without freely available tools, software and guidance. I am convinced that when taking stuff from a community, one should also use best efforts to contribute. Let this be my humble contribution.

Hope it may provide some inspiration or help to other people considering building their own blog or webpage and looking past the well-trodden CMS, Wix’es or Squarespaces of this world.

(And, of course, it is also a handy project manual for myself, should I wish to embark on similar projects in the future.)

1. SSG instead of CMS #

Blog platforms and CMS #

In the past I used many blog platforms and content management systems to build blogs, mainly Blogger, Drupal and Wordpress (both self-hosted and on wordpress.com).

They are relatively easy to set up, have a wide network to tap into and are mostly free(mium). Hosting a wordpress or drupal increases complexity, but gives nearly unlimited control. Posting is easy as can be, with nice wysiwyg editors. However, they are also cumbersome and heavy. They feel like overkill for a tiny simple personal blog like this one. So I went on th lookout for an alternative.

Website builders or content-platforms #

Websites like Wix and Squarespace are less ‘cumbersome’, give lots of control and have you up and running fast (if you don’t mind paying). Substack and medium.com are content-based platforms that are even easier and are very content-focused.

However, for a hobby-project like this one, I do mind paying. I also do not want the lock-in such platforms entail (I could as well have stuck to LinkedIn blogs then…), and wanted more control than medium or substack offer.

Static site generators #

Then I bumped into the concept of static site generators. These tools compile a website based on a template and content. Instead of relying on a database that is extracted to a front page (as do content management systems), they generate separate pages that simply link to each other (a static site). The result is a sleek and fast website, as the website isn’t making calls to an underlying database or running an underlying javascript for every click. For the same reason, it is also supposed to be more secure. An elaborate description can be found here.

The main downsides are the following:

1. a static website is, well, static. There is no going back and forth and no user input possible. That is not an issue for a blog like mine - I am writing, you (the reader) are reading. And if I would require dynamics in the future, there are several tools that make it possible to integrate dynamic elements, like Disqus.

2. there is a learning curve and a bit of tinkering involved. This is not a ‘get it up and running in 10 minutes’ type of thing. But then, isn’t that part of the fun?

As I don’t mind the downsides and like the idea of having a sharp tool that is as simple as it can be do get the job done, I went for it.

2. The choice for Hugo #

This website was built using Hugo, a static site generator.

I ended up choosing Hugo for a.o. the following reasons:

• I started out in Jekyll, but couldn’t get the hang of it.

• While building with Zola, I experienced compiling issues that seem to be linked to me working from a windows machine (see link_text). Hugo did not have such issues. Your mileage may vary.

• There is plenty of useful documentation for Hugo. The community seems active and helpful. Generally speaking, I was quite comfortable very fast in Hugo as well. Your mileage my vary.

• Hugo is supposed to be faster than Jekyll (although the difference has grown smaller over the past years).

• Hugo is simple, easy (once you get the hang of it) and fast. It can be explained in 40 minutes. And there’s plenty of good articles and youtube movies doing exactly this.

Depending on preferences other SSGs might be better suited to your wishes. Other ones I considered were zola (which is supposed to be even faster than Hugo) and Jekyll (which powers github pages, so is quite popular as well), but there’s many more (eg Sveltekit, Pelican, Hexo, Middleman, etc.).

3. Picking a theme: Whiteplain #

A theme is important, as it basically determines the lay-out of the website. I am not sufficiently comfortable in my html/css/javascript skills to write my own theme yet, so went on the lookout.

The hugo-website has a very useful list of themes, which contains some true beauties that are fit for all purposes.

For now I settled on Whiteplain, which I modded a bit. It is made available under MIT license, so it can be used quite freely.

4. Hosting: github pages #

There’s many options to host a static website. As you don’t need a database, you can basically host it on any domain that has FTP access.

I settled on github pages because it is easy to use (once you get the hang of the git basics), fast, free, and secure (as I do not wish to purchase a domain name for now). Its main downsides (less control over URLs, low cache expires, need to use a subdomain) are less relevant to me.

Note that I only used github pages to host my hugo-built website, I did not design the website using github pages (which is an option as well - such websites are powered by Jekyll).

Other hostings that come by often when looking for Hugo hosting are netifly, gitlab, AWS amplify and Azure static web pages. Hugo documentation provides inspiration and assistance.

5. Writing: IA writer and notepad++ #

Hugo does not have a wysiwyg editor. Instead, content is written in markdown. If you aren’t used to this, it is a bit of a learning curve - but it’s easy to grasp. A complete guide is available for free here.

There are many purpose-built markdown editors out there (eg, for web dilinger, for linux & windows ghostwriter, for mac macdown).

The one I have been using for a couple of years now is iA writer (available for mac, windows, android, ios - but you need separate licenses for each device). I love the way it looks, handles files, its fonts, its live preview, its typewriter view and active sentence highlighting and its very extensive export options if I want to build my writings to pdfs or word documents. But here too, your mileage may vary. IA writer is not cheap and with the good free alternatives available, you might not be inclined to purchase right away (but trust me, the investment is worth it if you write a lot).

In addition, for editing CSS or html, i find notepad++ (for windows) very convenient. On mac I have used atom (which is also available for windows and has github integration) for similar purposes. Both pieces of software are powerful, reasonably fast, give good syntax coloring and are free. I generally prefer notepad++ over atom, but that might be because I have be working with it for ages.

6. Bringing it all together: setting up the blog #

There are various guides and how-to’s on how to build a website using the above tools. If you like to tinker and google and have a few hours to spare, it isn’t as hard as it might sound.

I especially found the “creating a blog with Hugo and Github in 10 minutes” video by Ryan Schachte extremely useful, as this is exactly what I have been doing. There’s other video’s doing the same thing (eg. here and here). There are also some useful blogposts with detailed instructions (see ao here and here).

Most of the below will basically be a write-out/summary of these videos and blogposts, here and there with some additions. I will not make screenshots - the above video’s and posts would be better for that. I will mainly write out the process I followed - both for own future reference, and to give you an idea of what might work for you.

Note that I am using a windows 11 machine (and powershell) - so if you are using a unix based system, other guides may be more useful. I also am not a professional programmer or engineer, so the below might not be the best way to do things - but so far it is the way that has worked for me.

6.1 Install Hugo and Git #

Let’s start by installing Hugo. To be able to get Hugo, we need a content manager. I used scoop, others (ao Winget and Chocolatey) are available. To do so, I first had to set my execution policy (of course in powershell).

Set-ExecutionPolicy RemoteSigned -Scope steve

Then install Scoop.

iwr -useb get.scoop.sh | iex

And Hugo (go for the extended version).

scoop intall hugo-extended

If you are going to be using github (as I did), you will also need Git installed on your PC. I would suggest to follow the installation guide available on Github.. A grapical interface is available, but Git Bash is what you will need, as it allows to use text-based commands.

Alternatively (and this is the approach I followed), you can install posh-git in the powershell (see the guide here and even more detailed guidance here if the below wouldn’t work for you or if you need additional guidance), allowing you to communicate with github through the powershell. To do so we will install posh-git, import it into the powershell profile.

update-module powershellget -force

install-module posh-git -scope steve -force

import-module posh-git

add-poshgittoprofile -allhosts

6.2 Get a github account and set up two repositories #

Go to Github.com and open an account if you do not have one.

We’ll set up two repositories - one where your files live and one from which your website is deployed. This gives some additional freedom if you want to keep drafts online without publishing them etc.

In github, make two new public repositories:

• one I called ‘Blog’ (this is where the files live);
• the other one I called username.github.io (so in my case SV1124/SV1124.github.io). This is from where my files are deployed.

In Powershell, clone the Blog repository and open it.

git clone https://github.com/SV1124/Blog.git

cd Blog

6.3 Actually make the new website #

Next up: rendering the new website.

hugo new site stevenssnippets

And opening it.

cd stevenssnippets

Now you find yourself in the Hugo file structure.

6.4 Install my theme #

As indicated above, I went for whiteplain.

In stevenssnippets, I opened up the themes folder.

cd themes

Then installed the Whiteplain theme.

git clone https://github.com/taikii/whiteplain.git

Went back to the stevenssnippets-folder, opened Hugo.toml and copied the whiteplain configuration file in there (available here).

In the Hugo.toml file (which I opened using notepad++), the baseurl should be the github pages repo (including “/” at the end).

baseurl = "https://sv1124.github.io/"
title = "Steven's snippets"
theme = "whiteplain"

This is where I gave the website its first ’testrun’ from the ‘stevenssnippets’ folder.

hugo serve

Now, in my browser, a live version was available on localhost:1313.

6.5 Populate with content #

This is also where I added some ’test content’. In the ‘content’ folder, I have the below file structure.

about   
- _index.md
archives   
- _index.md
categories
- _index.md
posts
- post1.md
- post2.md
categories
- _index.md
_index.md

Every post starts with the below header.

+++
title = "title text"
date = "yyyy-dd-mm"
author = "author name"
tags = [
 	"tag1",
	"tag2",
	"tag3",
]
categories = [
	"cat1",
	"cat2"
]
+++

I also messed around a bit with the partials of the template (in particular header and footer, as well as the templates for ao my archives page) but that would bring us too far here.

6.6 Setting up the second repo #

Now, in Powershell, back to my desktop. Over there, made the second repo.

git clone https://github.com/sv1124/sv1124.github.io.git

Open it up.

cd sv1124.github.io

Set up main branch.

git checkout -b main

Make a readme file to avoid having an empty repo.

new-item readme.md

Commit that new readme to github, with the message “readme”, and push it to the main branch.

add .

commit -m “readme”

git push origin main

Now, on github.com, we can check the new ‘main’ branch being available & the readme file being included in there.

After this, went back to my \blog\stevenssnippets folder, to add a git submodule, which allows me to keep a git repo as a subdirectory of another repo.

git submodule add -b main https://github.com/sv1124/sv1124.github.io.git

Now, when opening the public folder in \blog\stevenssnippets\public, the readme document created above is available there as well.Using the command

git remote -v

You can see that the git in fact refers back to the other repo.

6.7 Deploy and enjoy! #

Went back to \blog\stevenssnippets, and built the website with Hugo.

Hugo

Hugo has now done its thing compiling template and content, and the built up website is available in \blog\stevenssnippets\public.

Open that folder.

cd public

And now, deploy.

add .

commit -m “initial deployment”

git push origin main

This step 6.7 will be repeated for every amendment to be made to the website.

After 5 to 10 minutes (sometimes even after 1 or 2 minutes) the website is available on github, and on github pages (i.e. https://myusername.github.io, in my case https://sv1124.github.io).

Enjoy (and let me know if any of the above doesn’t work!).

7. Updates and changes #

7.1 LF and CRLF #

When adding my files to github, I always got the following warning:

warning: in the working copy of ‘$$’, LF will be replaced by CRLF the next time Git touches it

On the basis of this very useful answer on stackoverflow, and the git documentation on this matter, I learned that this is due to the difference between unix systems presenting the end of a line with a line feed (LF) and windows with a carriage return and line feed (CRLF). The theme I am using was likely coded using a unix system, hence the warning.

I turned off the warning with the following command, which in fact auto-converts CRLF line endings into LF when I add a file to the index, and vice versa when it checks out code onto your filesystem.

git config core.autocrlf true

I understand from the documentation that this should not be used too lightly when cooperating with people on other machines, but as I am not a programmer actually using git to cooperate, for me that’s not a major issue.

7.2 Theme update #

As I felt the Whiteplain theme became too complex to manage and keep up to date, I switched to an even simpler theme, thomfran/typo. 30 mins of work, and up and running. See https://github.com/tomfran/typo. Considering moving to something even simpler.