Intro

I used to have a blog, but it was running on a theme that was becoming less and less maintained. Eventually, the moment had to come: burn it down and start again from scratch.

Starting fresh felt like the right decision — not just technically, but also as an opportunity to refactor and polish my blog.

On The Value of Blogging.

This blog exists as a place to think slowly.

Most technical work is ephemeral: incidents fade, decisions are forgotten, and lessons learned are rarely written down. Blogging is my way of pushing back against that.

Writing forces clarity. It turns intuition into explanation and highlights what I don’t yet understand. The goal is not completeness or authority, but honesty.

There is no schedule and no algorithm to please. Some posts may be rough, others precise. If these notes help someone else along the way, that’s a bonus — but not the objective.

The Tech choice

For this new iteration of my blog, I chose Hugo with the HBStack theme cards, deployed on GitHub Pages.

Why Hugo?

Hugo is a fast, opinionated static site generator that focuses on content first.

Once generated, the site is just plain HTML, CSS, and JavaScript — easy to host, easy to secure, and extremely fast.

For me, Hugo offers:

Excellent performance
No runtime dependencies
A simple content workflow
Long-term stability

Why HBStack and its themes?

HBStack builds on top of Hugo using modules, offering a flexible and well-structured ecosystem of themes and extensions.

What really sold me was the availability of hooks, which allow deep customization without forking or hacking the theme itself (js,css or html).

Some HBStack features I consider essential for my blog:

Post and documentation layouts
Sidebar and table of contents (TOC)
Emoji and Bootstrap icon support
Notification badge for new articles
Customization hooks
Syntax highlighting
Comment system (Giscus, backed by GitHub)
Light / Dark mode
Search index

Why GitHub Pages?

GitHub Pages provides a simple, reliable hosting solution for static sites. Combined with Hugo, it allows me to:

Host the site for free
Version content alongside code
Deploy automatically via GitHub Actions
Avoid server maintenance entirely

Start from scratch

It’s always better. Even though, I had already a blog, I started from scratch and imported the content and assests in the new blog to avoid all the assles.

This maybe repeating the tutorials here but just for the records:

 1# install go
 2sudo apt install golang-go
 3go version
 4
 5# install Hugo
 6HUGO_VERSION="0.148.0"
 7curl -LJO https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
 8tar -xzf hugo_extended_${HUGO_VERSION}_linux-amd64.tar.gz
 9sudo mv hugo /usr/bin/hugo
10hugo version
11
12# install nodejs 16 or higher
13sudo apt install nodejs npm git
14nodejs -v
15
16# install Dart Sass
17npm install -g sass
18sass --version
19
20# clone theme 
21git clone --depth 1 https://github.com/hbstack/theme-cards
22cp -r theme-cards/exampleSite mysite
23cd mysite
24sed -i '1s/.*/module github.com\/user\/repo/' go.mod
25sed -i '/^replace/d' go.mod
26
27# Install hugo dependencies
28npm ci
29
30# Run locally
31npm run dev

Tweak the config

The basics

1# in ./config/_default/hugo.yaml
2baseURL: https://mozebaltyk.github.io/
3title: Bałtyk Blog

Change background

1# in ./config/_default/params.yaml
2hb:
3  background_image:
4    brightness: 10
5    modern_format: webp

then put images in assets\images\background.jpg

To organize menu and add icons

Either define in ./config/_default/menus.en.yaml:

1main:
2  - identifier: navigate
3    name: Navigate
4    weight: 9
5    params:
6      icon:
7        vendor: bootstrap
8        name: signpost-split
9        color: "#fd7e14"

then you can defined the children like ./Categories/_index.en.md with :

 1---
 2title: Categories
 3menu:
 4  main:
 5    parent: navigate
 6    params:
 7      icon:
 8        vendor: bs
 9        name: folder
10        color: orange
11      description: All of categories.
12---

or directly from the index.en.md:

 1---
 2title: Posts
 3menu:
 4  main:
 5    weight: 1
 6    params:
 7      icon:
 8        vendor: bs
 9        name: body-text
10        color: "#20c997"
11      description: Some posts on IT topics.
12---

Change the back-to-top icon

1# in ./config/_default/params.yaml
2hb:
3  back_to_top:
4    animation: true
5    icon_height: 2em
6    icon_name: hand-index
7    icon_width: 2em
8    position_bottom: 1rem
9    position_end: 1rem

The Taxonomies

Taxonomies give structure to a growing collection of articles.

They allow posts to be categorized, indexed, and connected to one another beyond simple chronology. Instead of a linear stream, the blog becomes a graph: topics intersect, ideas resurface, and related articles can be discovered naturally.

In practice, taxonomies help both the reader and the author. Readers can navigate by themes rather than dates, while I can spot recurring subjects, gaps, or patterns in what I write over time.

Used well, taxonomies are not just metadata — they are a lightweight form of knowledge organization that keeps a blog coherent as it evolves

in params.yaml, you can tell sidebar which one to use to propose some switch button:

 1hb:
 2  blog:
 3    sidebar:
 4      taxonomies:
 5        count: true # whether to show the number of posts associated to the item.
 6        limit: 10 # the maximum number of the item.
 7        style: pills # pills, tabs or underline.
 8        separate: false # whether to separate into mutliple sections.
 9        authors:
10          disable: true # whether to disable this taxonomy.
11          weight: 1 # the weight of this taxonomy, lower gets higher priority.
12          count: false # override the global count setting.
13          limit: 5 # override the global limit setting.
14        categories:
15          disable: false
16          weight: 2
17        series:
18          disable: false
19          weight: 3
20        tags:
21          disable: false
22          weight: 4
23          limit: 25

Editing some content

Based on the Archetypes that I defined, I can create a new posts :

1hugo new --kind posts posts/my-new-blog.md

or docs:

1hugo new --kind docs docs/Devops/IaC/index.md

A word on giscus

In ./config/_default/params.yaml, there is giscus blocks config. Giscus is a comments system powered by GitHub Discussions, so the comments left on your articles goes in discussions of your github Pages.

To do so, you will need to:

Make your repository public.
Enable discussions in the project settings.
Activate giscus app for on your account (you can limit to your blog project)
Then, giving the URL of your repository

 1hb:
 2  blog:
 3    giscus:
 4      repo: MozeBaltyk/mozebaltyk.github.io
 5      repo_id: R_kgDOKJSCfA
 6      category_id: DIC_kwDOKJSCfM4CYvA_
 7  docs:
 8    giscus:
 9      repo: MozeBaltyk/mozebaltyk.github.io
10      repo_id: R_kgDOKJSCfA
11      category_id: DIC_kwDOKJSCfM4CYvA_

On their side, visitors will need a Github account and must authorize the giscus app to post on their behalf using the GitHub OAuth flow.

Shortcodes

NB: remove the backslash to use those blocks of code.

Toogle of config files between toml/yaml/json:

1\{\{< bs/config-toggle "params" >\}\}
2hb:
3  blog:
4    home:
5      pinned_posts_position: list
6\{\{< /bs/config-toggle >\}\}

This one is a nice one, since it automaticly create a block of code with 3 tabs to switch between the 3 type of config (TOML/YAML/JSON) like below:

params.toml

1[hb]
2  [hb.blog]
3    [hb.blog.home]
4      pinned_posts_position = 'list'

params.yaml

1hb:
2  blog:
3    home:
4      pinned_posts_position: list

params.json

1{
2   "hb": {
3      "blog": {
4         "home": {
5            "pinned_posts_position": "list"
6         }
7      }
8   }
9}

Some banner for info, warning, etc:

1\{\{< bs/alert info >\}\}
2\{\{< markdownify >\}\}
3This is the old version of this blog. But last update of hugo version did not work well so I decided to move on to the hbstack theme. I keep this article since it was the first one of this blog. 
4\{\{< /markdownify >\}\}
5\{\{< /bs/alert >\}\}

give this effect:

Example of informational banner

Refere to this doc for all the examples.

The list of all shortcodes

Images

Featured image:

The first image of the images parameter, usually used for static and external images.

The page image’s resources that naming in pattern feature*, such as feature.png, featured-xx.jpg. The featured image resource will be resized in smaller size, to save user’s and server’s bandwidth.

Image used in article goes in static/<article name>/image.jpg

Deployment

On this side as well, there is improvment since a new docker images with all dependencies is provided on docker.io. Which is the local testing of the blog and reproductibilty.

But the github workflows deployment in .github/workflows/gh-pages.yaml with a build job and a “deploy” job which trigger when I push on main.

Bonuses

At this stage, what could you do more:

Share your website with the HB to showcase that you are using HB theme on their hompage. doc
Create custom widget like in this article
Check the uptime of your site with a simple github action
Auto-update with renovate.json
Write your docs with Obsidian: Here are some elements about how to set it correctly.
Dig into shortcode