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
Top comments (0)