Introduction

As some of you may notice, I have been playing with some blogging softwares for the last 2 years. Like most of the people I have started blogging with Google’s Blogger and switches to Wordpress. They were all nice, however I was looking for something more straightforward and have more control. Knowing that I am not a web developer, most of the sections in Wordpress and others were totally out of my understanding.

By the way, I also remembered that I tried Wix.

If you would like to stick with their templates and methods, Wordpress, Wix, GoDaddy etc, are all good products.

Here, as an engineer, I was looking something more, and discover the world of self hosting, and started checking different categories of it, then I found myself in Static Site Generators which I have never heard before. There were many opensource softwares listed, and they have huge amounts of stars in Github and noticed that it is widely used.

First, I tried to understand the logic of the Static Site Generators, actually today I realize that at first sight I misunderstood it. Frankly speaking, I really like the overall idea of Markdown formatting because it eases many things, and increases the efficiency (at least in my case). In Static Site Generators, all the things I read is surrounded by Markdown, but I was looking for a UI/GUI to perform some administrative work. In fact, It took really long that I understood there is no need for it.

Getting into SSG

The first software I used was Grav, I deployed it on a Docker container, and configured the Reverse Proxy on Nginx Proxy Manager. It was working fine, however the infrastructure was not much satisfactory that I had some issues with it. But my real problem was that I was not really using markdown files. I deployed the Admin interface for Grav, and was doing everything from there. I was using a Static Site Generator, but using it like I was using Wordpress. This was not the methodology I wanted to have.

Apart from the above concerns, of course out of my curiosity, I continued to test some SSG software on my local such as Ghost and Hugo. I don’t know why but I found Hugo close to myself. I moved my blog to a server with higher resources, and started serving my blog generated from Hugo. I am feeling relieved, relaxed and more with positive emotions. I might do the same things with Grav, but Hugo also very nice.

I like the idea of being capable of doing everything from command line, and generate all the website from it. Of course there are some settings I needed to do, but in general it is only forming a file with Markdown, selecting a nice theme from Hugo website

Styling

At my first blogging days, I was so much into the design and nice shape of the website, my idea was that the website should look gorgeous. Probably, since I am getting old, I started to check for more simple things, and like the Archie theme. When compared to more popular themes, it has more way to go, but I really like its simplicty. This theme has a large portion of the role to select Hugo.

Configuring this Blog

Here comes the part of the real aim of creating this article. I will try to tell basic steps for configuring a website (it doesnt have to be a blog) with Hugo. Initially, we need to understand core components of serving a website.

1. Infrastructure.

2. A web service which can be reachable from internet. This web service will serve the website contents from a service like Apache, nginx etc.

3. Installing Hugo.

Hugo can be installed through its website guidelines according to your OS environment.

Check the documentation here, and perform the installation accordingly. Having git in your environment will also be beneficial as we will use it for installing the theme in the next step.

The first thing to do with Hugo is to create a site.

hugo new site blog

The above command will create a blog directory, and place all needed files to build a website. Here we can install our favorite theme to Hugo.

4. Installing Hugo theme

As stated in the previous step, we will need git to perform some certain activities. Now lets get into installing a theme. As mentioned above, I will use Archie

I also recommend checking the Github pages or the theme website if there is any irregularity in installing the theme.

First, lets create a git repository from the created blog site.

cd blog
git init
git submodule add --depth=1 https://github.com/athul/archie.git themes/archie
git submodule update --init --recursive
git submodule update --remote --merge

5. Adding Content to Blog

This is the step to add more and more content to your website. Here, we will use the hugo command line tool to perform some certain things.

In this part, the most important step is that hugo command can be run only inside the site folder. Therefore, always ensure that you are under your site folder.

hugo new content about.md

Hugo requires to create a page object with a .md suffix, so that it will know it is a markdown file. The above example will create about.md file under content directory. We can also create more files using the same command.

hugo new content blog/post1.md
hugo new content blog/post2.md

The above commands will also create files under content directory, but it will also create a blog folder and place the files under it. Thus it will look like as follows

blog# ls -lR content/
content/:
---------------------- about.md

content/blog:
---------------------- post1.md
---------------------- post2.md

There is one thing important to mention about creating a new content, which is metadata templating, and this can be found under archetypes/default.md file. This file contents are prepending to all newly created content files, and the statement draft = true makes the files anticipated as a draft file unless the it is not to true. But don’t worry, there are also several flexibilities in Hugo if you would like to build drafts as well.

After creating the content file, it will be only a matter of modifying the text file with a markdown format, and there comes the other step.

6. Hugo site configuration

Depending on how create the site, hugo can generate different types of configuration files in yaml, toml or json format. Depending on your favorite format, you can check how to fill the configuration file. The configuration file name is hugo.toml in my case. For yaml users, it will be more less with toml that toml has equal = sign in between settings and values, instead yaml has colon : and some dash - notions.

Some important settings are as follows, but dont forget that the theme you are using can add more settings to this file. That’s why you always need to check the theme website for such advanced settings.

baseURL = 'https://www.emrekurnaz.info/'
languageCode = 'en-us'
title = 'Emre Kurnaz`s IT Dairy'
theme = 'archie'

With the above settings, we define the baseURL, website language, title and theme name. The next time hugo command is executed these settings will take place and the website will be updated.

7. Deploying the website

OK, we are in the final step of our website/blog content filling (I have respect to developers, so that I am trying to stay away from saying developing the website).

Hugo has a capability to serve a web service on a local port on localhost by default, this might be used as a way to see if your website is running as you want, or you can just directly deploy your website into your web service root folder, to make it directly available to internet.

So, first lets talk about local serve. hugo has a subcommand named server. When you run under your site folder, it will generate an output like the following

blog# hugo server
Watching for changes in /DOCKER/_compose/hugo/site/blog/{archetypes,assets,content,data,i18n,layouts,static,themes}
Watching for config changes in /DOCKER/_compose/hugo/site/blog/hugo.toml
Start building sites …
hugo v0.123.7+extended linux/amd64 BuildDate=2024-04-01T05:53:48Z VendorInfo=ubuntu:0.123.7-1build1


                   | EN
-------------------+-----
  Pages            | 85
  Paginator pages  |  1
  Non-page files   |  0
  Static files     | 58
  Processed images |  0
  Aliases          |  1
  Cleaned          |  0

Built in 96 ms
Environment: "development"
Serving pages from disk
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)

As seen from the output, the internal hugo web service is running on localhost and reachable from http://localhost:1313

There is no any SSL on this URL, as you need to remember that this is only for checking if the content is fine.

Ports and bind address can be changed from the hugo command line using -p/--port for updating the port and --bind to update the bind ip address. Besides, if you would like to check the draft content in a webpage, you can also use -D/--buildDrafts option. This will also force hugo to build the drafts and generate the website drafts included.

Until now, if everything is ok, then the website can go live. It is always good to have a backup of your existing website before updating it. Without any given options hugo can generate the website under public folder. Hugo also have an option to generate the output to a different location in the system. What I am doing currently (not fully sure that it is correct). I am creating a backup of my existing website root folder.

cp -a /var/www/html/ /BACKUP/website/$(date +%F)/

Then generating the website onto the webfolder.

hugo -d /var/www/html/

With the above command, hugo generates to website directly to /var/www/html/ where my website is running, and it is only updating what is new. But it is also possible to use --cleanDestinationDir option, if there is no any files from what hugo creates. Otherwise, this will first delete everything in the webroot folder then generate the website. Therefore, if you have some customizations out of Hugo, be careful using this option.