how i built this blog (and why i stopped overengineering it)

25 Apr, 2025

a story, a mini tutorial, and a gentle reminder to keep things simple.

prelude

i wanted a blog. not a startup. not a product.

act i – the overengineer awakens

Like many engineers with too much curiosity and not enough constraint, I started building it from scratch.

My initial setup was:

Next.js
Keystatic as a CMS
inspired by Timo’s setup, which is very slick

The idea I had was:

markdown-based content
real-time preview
full customization
Unlimited Power™

I spent hours tweaking folders, configuring content collections, thinking about image optimization, theming, deployment… and not the actual content.

act ii – too much for what i needed

it worked. but it was heavy. and most importantly: I still wasn’t writing.

I had built a system that required energy before I could even think about writing words.

act iii - enter obsidian + hugo

Then Leo, my partner, sent me this blog post. I read it and immediately thought: yes, this is what I want.

I went with this simple workflow:

write in Obsidian - which I already use daily for notes
organize posts with frontmatter
sync to a folder
publish with Hugo through Netlify

I also chose Bearblog Hugo theme, similarly to the author from the original post. It gave me:

clean, minimalist design
good typography out of the box
no JS bloat
easy overrides when I want to customize things later

it took 1 hour to set this up.

act iv – the tutorial (finally)

These steps outline what I did. There are many other ways to set up your content management, hosting, CI/CD pipeline, etc. You may be happier self-hosting everything at home, or using more sophisticated setup.

install Hugo

I use Homebrew:

brew install hugo

confirm it worked:

hugo version

create a new site

hugo new site my-blog
cd my-blog

add the theme (i chose Bearblog)

git init
git submodule add https://github.com/janraasch/hugo-bearblog themes/hugo-bearblog

then, update hugo.toml (or config.toml) with the theme:

theme = "hugo-bearblog"

create your first post

hugo new blog/hello-world.md

you’ll find the file in `content/blog/hello-world.md

connect Obsidian (or any editor) to content/blog/ folder, and fill in the frontmatter (tips on how to add frontmatter to Obsidian note here):

---
title: "hello world"
date: 2025-04-24
draft: true
---

note that draft field is what Hugo looks at to decide whether a post should be published or hidden. Set draft to false to publish the post.

run your site locally

hugo server -D

open your browser at http://localhost:1313

add a favicon (optional)

drop favicon.ico into the static/ folder and favicon.png into the static/images folder.

you may also want to tweak the header layout of your site (i added the same image used for favicon next to my blog title).

if you want to make changes to layout (optional)

you can fully customize the look and feel of your site.

let’s take an example of appending an image to site’s title. inspect the theme you use - notice where the title is placed:

<a href="{{ "" | relURL }}" class="title">
	<h2>{{ .Site.Title }}</h2>
</a>
<nav>{{- partial "nav.html" . -}}</nav>

to change header layout partial for your version of the site, you’ll just need to copy this file to your own layouts/partials folder, and change it as you like, for example:

mkdir -p layouts/partials
cp themes/hugo-bearblog/layouts/partials/header.html layouts/partials/header.html

<a href="{{ "" | relURL }}" class="title" style="display: flex; align-items: center; gap: 10px;">
	<h2>{{ .Site.Title }}</h2>
	<img src="/images/favicon.png" alt="favicon" width="50" height="50">
</a>
<nav>{{- partial "nav.html" . -}}</nav>

add index (home) page content

add _ index.md file to the content/ folder and treat it as any other MD file. add some welcome information about your blog there.

#### Hey, this is my blog!
Welcome :)

deploy (i used Netlify)

you can push your repo to GitHub and connect it to Netlify or any other product, or self-host your site.

for build, you can use

hugo --minify

to generate the public/ folder with minified html for static hosting anywhere.

with Netlify, i added a netlify.toml config, where i set target version of Hugo to use:

[build.environment]
HUGO_VERSION = "0.146.7"
HUGO_ENV = "production"

act v - the takeaway

Sometimes, building things from scratch is fun. Sometimes, it’s a creativity trap.

Tools should help you do the thing – not get in the way of it. This setup gets me to writing faster. And I can always tweak it later.

appendix

tools I used:

i’ll probably still overengineer something again in the future.

end

#Post #Software #Tutorial