Context

I wanted to start my blog with the simplest possible setup. As a software developer, GitHub Pages felt like the natural choice — it’s free, integrates cleanly with a Git-based workflow, and requires minimal infrastructure.

Reading the official GitHub Pages documentation they suggested to use Jekyll to create a website. Everything worked smoothly… at first.

But then I noticed the Jekyll plugin versions were outdated. As a best practice, bump the dependencies must be a common skill for a programmer, so I started updating the dependencies. That’s when the fun began — and by “fun” I mean “dependency chaos”

In this post, I’ll walk through the setup, the roadblocks I hit, and how I fixed them — with useful links and tips I’ll probably revisit myself.

Starting Simple

I bootstrapped the project using the Jekyll Quickstart. Got a basic site running locally, then set up a GitHub Actions workflow to build and deploy the site automatically.

To see who’s visiting, I decided to add some basic analytics. After some digging, I went with Simple Analytics — privacy-friendly and easy to set up. And also Umami for benchmark comparison. Was just adding a script tag in the HTML header.

Cool. But where’s the header?

Themes and Outdated Dependencies

Digging into the minima theme’s structure, you will find the base.html file that points to head.html file that refers to custom-head.html file. To add the HTML header, should be in this file but in your project.

I added only a configuration to collect analytics data only when it’s live. Because I don’t want to have metrics when I’m developing locally. So this condition will be fine:

{%- if jekyll.environment == 'production' %}
  <!-- your script analytics here -->
{%- endif -%}

And to have it work with Github actions, just add JEKYLL_ENV when building your website:

      - name: Build with Jekyll
        # Outputs to the './_site' directory by default
        run: bundle exec jekyll build --baseurl "$"
        env:
          JEKYLL_ENV: production

When I render the website the layout seems a little different from the demo, so I realized I was using an older version (v2) and not the latest (v3).

Following the broken windows theory, I decided to clean up and upgrade the theme. The minima GitHub repo has a good instructions on how to use the newer version.

I did the same for for Jekyll version. Based on the Github page dependency, they support by default the version 3 of jekyll, but by configuring the Github Actions, I could use the verison 4.

Gotchas with GitHub Actions and Local Builds

✅ Tips That Helped

  • Pin your dependencies versions. For ruby version, jekyll version and theme version. Then we can avoid some mismatches between local and GitHub Actions environments.
  • Add bundle config set --local path 'vendor/bundle' to isolate gem installs.
  • If plugins break, check for exact version compatibility in the GitHub Actions Jekyll docs.
  • To customize your site by adding the analytics, read the documentation always.

Conclusion

What started as a simple blog setup turned into a fun debugging session. But in the process, I learned a lot about how Jekyll, themes, Liquid templates and GitHub Actions really work together.

If you’re starting your own blog or bumping version of old one, I hope these notes save you some time.

Up next: how I’m adding custom components, organizing my posts and making the blog a little more me. Stay tuned!