Howdy Jekyll Theme

On a whim, I decided I wanted to build a fresh portfolio theme using Jekyll. When I went looking for inspiration, the theme landscape was rather stale. So I did what any reasonable person would do: I spent a month building my own and publishing it as a Ruby gem.

This is the story of how that went.

Where It Started

While playing with Framer I came across one of their templates called axel. Liking it so much, I took the look and feel and ported it to Jekyll — layouts, includes, collections, the whole pipeline. Then improved the mobile experience and added a bunch of features all easily configured in _config.yml.

The theme is called Howdy because I wanted something friendly.

How the Gem Works

The entry point is about 15 lines of Ruby. It registers a Jekyll hook that injects the theme’s _layouts, _includes, and _sass paths at build time.

Jekyll::Hooks.register :site, :after_init do |site|
  theme_root = Howdy::Theme.root
  site.layouts_path = theme_root.join("_layouts").to_s
  site.includes_load_paths << theme_root.join("_includes").to_s
  site.sass.paths << theme_root.join("_sass").to_s
end

The Sass uses modern @use syntax. The entire design system lives in CSS custom properties in _variables.scss — colors, spacing, radii, transitions. Dark mode just overrides the same variables.

The hero carousel uses Swiper.js with a fade effect and 3-second autoplay that pauses on hover. It only loads on pages that have more than one hero image. No point shipping a carousel for a single image.

The CI / CD Saga

The CI pipeline went through more iterations than the theme itself. Having never done this myself, opencode played a critical role in helping me debug the workflow.

Playwright browsers hung in CI until I switched to the official Docker container with pre-installed browsers. That container runs Ubuntu 22.04, which doesn’t have libyaml or build tools — three apt packages, two hours of my life.

Deployment started with actions/deploy-pages, then switched to branch-based GitHub Pages with peaceiris/actions-gh-pages; the deploy only runs on push to main, not on PRs. The release workflow is now fully automated.

Things I Learned the Hard Way

• bfcache breaks page transitions - When the user presses back, the browser restores the page from cache — but my “navigating” class was still applied, leaving the content invisible. The fix was a pageshow event listener that clears the transition state on restore.
• Firefox scrollbars are different - They use scrollbar-color and scrollbar-width, not ::-webkit-scrollbar. You have to style both.
• Safari ignores loading=”lazy” on SVGs - No error, no warning. They just load eagerly.
• The gemspec glob must match every file - If you add a file type that doesn’t match the Dir[] patterns in the gemspec, it won’t ship in the built gem. No feedback loop. Just a missing file.

Where It’s At

howdy-jekyll-theme is currently v1.0.9 on RubyGems. Lighthouse 1.0 across all four categories. 23 Playwright tests. Four required status checks on every PR. 1,100+ lines of Sass. MIT licensed.

A live demo is hosted on Github Pages. The source is on GitHub if you want to use it, break it, or contribute. Enjoy!