After trying every ready-made Hugo theme out there, I still decided to write my own. This post records the process and the thinking behind it.
Why build a theme from scratch #
Ready-made themes have two problems:
- The aesthetics never fit: no matter how long you browse the theme gallery, nothing feels quite right;
- Customizing them is a detour: to change one small detail, you first have to read through hundreds of lines of someone else’s templates before you can even override it.
The essence of a Hugo theme is actually very simple — HTML templates + CSS. No frameworks, no build toolchain. A minimal usable theme needs just three files.
Design language #
The overall look is inspired by pixel / 8-bit retro style:
- Colors come from the classic Sweetie 16 pixel-art palette
- Zero border radius, 2px solid borders, and solid offset hard shadows
- Headings use a stitched pixel font while body text stays sans-serif for readability
Project structure #
The theme is split into clear layers to make iteration easy:
themes/pixel-blog-hugo/
├── assets/
│ ├── css/ # tokens / base / layout / components / markdown / home
│ └── js/ # light-dark toggle, mobile menu, back to top
├── i18n/ # UI strings in Chinese and English
├── layouts/ # templates and partials
└── theme.toml
Styles are concatenated, minified and fingerprinted via Hugo Pipes; theme details are carried by CSS custom properties, so the light and dark palettes only require toggling a class on the root element.
The homepage copy (params.hero), the header name and logo (params.identity), and the featured work section (params.works) all live in hugo.toml — you can change content without touching templates.
The goal: change one color value, and the whole site follows.
What’s next #
- Post search
- Archives and tag pages
- Comment system
- Lazy image loading