I also faced some difficulties getting started with the blog. I spent way too much time creating the Github Action that deploys my content to Netlify. I failed so many times before getting it right, I exceeded Netlify’s free tier 🤡. Most of the difficulty actually came from the “extra” functionality with Lychee link checking and Vale linting. Although I was able to get both of these tools running well locally on my machine, I ran into challenges getting them to run in the pipeline.

Linting with Vale was very difficult to nail down. I was able to get it to work reliabily in the local repository, but struggled with containerizing it and running in a pipeline. I also had invalid syntax in my Lychee link scanning for a while. I resolved both issues, but definitely got caught up in the weeds and did not write any new blog posts in the meantime.

I reposted [one of my old blogs from Medium](/posts/linux-frustrated-lovingI don’t), and realized Hugo doesn’t have a great way of centering images. You can use Hugo shortcodes, but those are specific to/dependent on Hugo, and in the interest of keeping the content as decoupled from the site generator as possible, I did not want to invest too heavily in shortcodes. I found a really helpful blog post on ebaddf.net that had a simple, elegant fix that should work across site generators.

It involves creating a custom CSS file, i.e. at static/css/custom.css:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

img[src$='#center']
{
    display: block;
    margin: 0.7rem auto; /* you can replace the vertical '0.7rem' by
                            whatever floats your boat, but keep the
                            horizontal 'auto' for this to work */
    /* whatever else styles you fancy here */
}

img[src$='#floatleft']
{
    float:left;
    margin: 0.7rem;      /* this margin is totally up to you */
    /* whatever else styles you fancy here */
}

img[src$='#floatright']
{
    float:right;
    margin: 0.7rem;      /* this margin is totally up to you */
    /* whatever else styles you fancy here */
}

And embedding images using that class:

1
2
3

![your_img](/img/your_img.png#center)
![your_img](/img/your_img.png#floatleft)
![your_img](/img/your_img.png#floatright)

Getting URL slugs to work for content nested in directories by year (i.e. content/posts/<year>/post-name.md in the source code) to work proved harder than I expected. I wanted to organize the source code for my blogs by year (both as a way to reduce clutter/page loads in Github, and because it’s easier to manage in a code editor), but I wanted the URLs to omit the year (i.e. /posts/post-name without the year).

I tried a few different things:

• Using the cascade configuration option to “collapse” URLs
  • This was supposed to move anything in subdirectories under content/posts/** up to the root posts/ path when building the site.
  • It worked, but it also caused /posts/ to return a 404 error.
• Creating a branch bundle with content/posts/<year>/_index.md.

  • This solution also made use of the cascade option, but in a more targeted way:

    1 2 3 4

    --- cascade: url: "/posts/:slug/" ---

  • I originally used headless: true, but this option contributed to my 404 problem, because I use /posts to aggregate all of my posts.

• Adding a slug to each page.
  • I tried adding slug: "url-slug-i-want". I even added it to my posts archetype
  • This apparently has no effect on bundles.

I found that using a slug to manually set the URL path works well. For some pages, the url option worked better. slug is for overriding the last segment of the path, i.e. /page-name/slug-name, while url gives full control over the URL path, even allowing characters that are reserved by the OS, i.e. adding colons : to a URL like http://example.com/my:example.

If both slug and url are set, the url parameter takes precedence

For posts, this looks like:

1
2
3
4
5
6
7
8

# archetypes/posts.md
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
slug: "/post-name/optional-sub-post-name"
## Settinng a URL too will override the slug
url: "post-name/optional-sub-post-name"

I am sure there will be many other challenges (for instance, I have not tried changing the blog’s theme yet, and that looks like a whole adventure if you rely on theme features), but the community forums are filled with very helpful threads, and it is relatively easy to find help for Hugo online. It’s a popular tool that’s well documented and has an active community. Some of the challenges I’ve faced are quirks or limitations of Hugo, while some are problems I would have had with any static site generator. I’m overall happy with the Hugo experience.

Tools

I am using Mise to handle installing all of the tools I need to develop/build the blog. The .mise.toml file in the repository defines these tools, so I can simply clone the repository, install Mise, and run mise trust && mise install on a new machine to get up and running. Mise is also useful in container environments and CI/CD pipelines, it can ensure I’m installing the same tools in every environment, with version pinning for ones I want to control upgrades for like the hugo CLI.

Taskfile is a new tool I found that lets you write YAML files to define tasks that can be called with the task CLI. It’s a very versatile tool, and because it uses an embedded shell, it’s (pretty much) fully cross platform. This is very useful, because it means the same tasks can run on Windows, Mac, or Linux, in CI/CD pipelines, Dockerfiles, etc. I use it for simplifying some commands I run frequently, like Docker commands or Hugo commands.

Vale is a utility that lets you define a style guide and lint text content against it. You can use predefined styles, like Microsoft or Google’s, and can mix and match. When Vale runs, it will surface writing and readability issues from the chosen style guides.

Lychee is a fast, easy to use link checker. I found it while setting up this blog, tried it once, and immediately added it to the stack. Lychee can scan live sites/URLs, but can also be pointed at the raw Markdown files that comprise this blog, or the rendered HTML. This allows me to catch broken links on the site before deploying, or to detect linkrot.

While setting up the blog I had to make a number of choices that affect the short and long term health of the blog. Deciding where and how to host the code and the static site, what tooling to add, how to structure the repository, etc.

Git Forge

Spoiler: I went with Github.

I considered many options for where to host the source code for the blog. Github is an obvious frontrunner, partially becaause I am already active on Github, but also the network effect. While I don’t promote my blog, I also like the idea that I’m not just shouting into the void with my posts, and discoverability is best where the people are.

Github hit one billion repositories on June 11, 2025, the first public forge to do so, highlighting the sheer amount of attention and usage on the platform. Most of my coding activity is still on Github (although I mirror many of my repositories to codeberg.org), so anyone stopping by my profile is more likely to find my blog.

One of my concerns while setting up the blog was the ability to quickly and easily move to a new Git host. If I want to move the blog to Gitlab or my own self hosted git forge, I don’t to have to labor to get back up and running. I plan to only dip my toes into a given platform; I will take advantage of some of the features, but will prefer external or embedded solutions for most things (sidenote: I need to find a way to keep issues out of Github.)

And so Github it is, for now.

CI/CD

I spent time planning the structure of the git repository for the blog to make it portable. I have seen a number of blogs switch platforms over the years, and the posts they write at the end of a migration have inspired some of the choices made for this blog.

For example, while this project is hosted on Github and I am using Github Actions to do things like lint the content and publish new pages, I also recreated the functionality in Concourse CI pipelines so I am not tied to a specific git platform. I could move the blog’s repository to any other remote, like Gitlab or Codeberg without breaking my CI/CD. At some point I will probably try writing the pipelines in Dagger to make them truly portable.

I also considered Woodpecker CI, which is a fork of Drone, Crow CI which felt a bit too simplistic, and Komodo. I may still integrate Komodo for GitOps like deploying on specific conditions in a PR.

Hosting

As of 01/24/2026, this blog is hosted on Netlify, a platform I have been looking for a reason to try. I disabled Netlify’s automated rebuilds on merges to main so I could write a deployment pipeline of my own, mainly for the experience, but also to ensure I don’t break the site when I’m trying new things. I hit Netlify’s free tier limit in 2 days because of all the pipeline failures…I mean “tests” that I ran…but the team was generous enough to refresh my credits when I reached out for support. +1 to Netlify!

Because the site is just static HTML/JS/CSS, I leave the option open to move the site’s hosting to basically anywhere. I build a production Docker image, so I could deploy a container somewhere and route the techobyte.cc domain to it, or simply copy the static files to any host that can serve files via a web server. This ensures I won’t get “stuck” with a specific host, or with a specific deployment method. I have heard of many bloggers who run their blogs off a Raspberry Pi they have in their house, and there’s really nothing stopping me from doing the same!

I also evaluated Fly, but decided they were more geared at full blown application deployments, Azure Containers, a Hetzner VPS I would have to maintain, DigitalOcean Droplets, and of course hosting it myself on a machine in my home, behind a reverse proxy.

Theme

This was a tough one… Hugo has a lot of themes. Most of them look good, some of them look great, but I had a few requirements in mind:

• Optimized for text-based posts. Most of my posts will be text-heavy, so optimizing layout for reading was an important factor.
• Simplicity, I didn’t want to use a highly customizable theme that would require a lot of configuration and tweaks.
  • I am aware of my tendency to find yaks to shave, and want to focus on writing.
  • Limiting myself to themes that are opinionated and rigid narrowed the selection pretty significantly.
• As generic as possible. Themes like Blowfish are amazing, but you have to go all-in to really take advantage.
  • I am building this blog for the long term. The ability to switch themes/site generators is highly appealing.
  • The more customization I need to do to the blog, the more I am building the site around the theme rather than the content.
• Content is front and center, no landing pages or superflous sections.
• Support RSS (this is officially supported by Hugo, but some themes handle revealing the functionality to readers better than others).

I decided to start with PaperMod as my theme. While it is kind of opinionated and has some theme-specific configurations, they seem easy enough to “rip out” if I ever want to change it later. It has a light and dark mode, and center-aligns the content for distraction-free reading. RSS setup was easy, and the icon is very obvious on pages that support it.