Finish-Up-A-Thon: How I Turned a Half-Finished Hugo Theme into a Standalone Shiki + Tailwind v4 Project

ouraihub — Mon, 01 Jun 2026 09:29:29 +0000

From Shared Modules to Fully Inlined: Finishing a Hugo Theme with Shiki, Tailwind v4, and CI Fixes

Every developer has at least one project that looks “almost done” for far too long.

For me, that project was hugo-theme-paper - a minimalist, responsive Hugo theme inspired by Astro Paper. It was built with a stack I still like a lot: Hugo v0.120+ Extended, Tailwind CSS v4, TypeScript v5.8+, esbuild, and Vitest. The intent was always clear: keep it elegant, keep it lightweight, and keep the reading experience clean.

But over time, the project accumulated the usual kind of finish-line debt:

too many external dependencies for something that should feel self-contained
code blocks that looked wrong in light mode
render hooks and workflow hacks that were only there to compensate for earlier decisions
a two-repository release flow that worked, but not smoothly enough

That is why I used the GitHub Finish-Up-A-Thon Challenge as the deadline to stop circling and finally finish the thing properly.

What I Finished

1. Removing `@ouraihub/hugo-shared` and inlining what the theme needs

The biggest refactor was architectural: I removed the external @ouraihub/hugo-shared dependency and inlined the needed modules directly into the theme.

This was a deliberate tradeoff in favor of simplicity.

Why it matters:

the theme is now truly standalone
users do not need to chase extra shared packages
cloning, testing, and installing are simpler
the theme is less exposed to version drift from another repo

I applied the same direction to the remaining shared pieces that previously lived outside the theme. The result is a theme that is much easier to consume as a Hugo Module without knowing anything about my internal workspace layout.

That is not the kind of refactor that gets applause in a screenshot. It is the kind that saves people time when they actually try to use the project.

2. Fixing light-mode code blocks with Shiki

The second big fix was visual.

The theme already had code highlighting, but the light-mode experience was not where it should be. Colors felt off, backgrounds did not blend naturally with the prose, and some old render-hook logic was still hanging around from testing days.

I tightened the syntax-highlighting path around Shiki and cleaned up the leftover rendering layer.

What changed:

light-mode token colors were corrected
code block backgrounds were aligned with the theme
redundant test render hooks were removed
prose and code now feel more cohesive

This was one of those refactors where the goal was not just “working output.” The real goal was polish.

3. Greasing the wheels of CI/CD

Because this project uses a dual-repository workflow, the release pipeline matters almost as much as the theme code itself.

The development repo handles source work and testing. The distribution repo, hugo-theme-paper-dist, carries the precompiled output that users can import through Hugo Modules.

That setup is fine in theory, but only if the automation behaves.

So I also fixed the GitHub Actions workflow:

corrected the clone and sync path for shared assets
removed brittle assumptions in the release process
aligned workflow steps with the current toolchain
reduced the chance of distribution-time failures

That turned the pipeline from “works most of the time” into something I can actually trust.

Why Finishing It Felt Good

The best part of this challenge was not adding more surface area. It was removing confusion.

After the refactor:

the architecture is simpler
the theme is more self-contained
the code blocks look right in light mode
the release workflow is less fragile

And the tests still hold up: 176 test cases pass, with 85%+ coverage. That is the kind of number that tells me this project is no longer just presentable, but actually healthy.

That is what finishing a project should feel like. Not just “I shipped something,” but “I finally made it coherent.”

If you like clean Hugo themes, readable syntax highlighting, and a pragmatic Tailwind v4 + Shiki setup, give hugo-theme-paper a star and try it out.

Repository

GitHub: https://github.com/ouraihub-hugo-themes/hugo-theme-paper

DEV Community: ouraihub