Why Automated Changelog Generation?

• Ensures consistency in changelog formatting
• Reduces manual effort and human error
• Maintains up-to-date documentation automatically

Prerequisites

These are the tools being used:

• Git-Cliff : A highly customizable changelog generator built in Rust.
• GitHub Actions : A CI/CD platform integrated with GitHub.
• github-signed-commit : A GitHub Actions that commit your files via GitHub Graphql API to guarantee verified commit on GitHub.

Initialize Cliff configuration

First, let’s install git-cliff CLI to do so. I will use the npm package for this example. However, you can visit Git-Cliff Installation for other package mangers.

npm install -g git-cliff@latest

Personally, I like the format cocogitto for its styling base on conventional commits.

git cliff --config cocogitto

This will generate a cliff.toml file in your repository root that contains info on how Git-Cliff processes your git commits:

# git-cliff ~ configuration file
# https://git-cliff.org/docs/configuration

[changelog]
# template for the changelog header
header = """
# Changelog\n
All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.\n
"""
# template for the changelog body
# https://keats.github.io/tera/docs/#introduction
body = """
<!-- generated by git-cliff -->
"""
# template for the changelog footer
footer = """
<!-- generated by git-cliff -->
"""
# remove the leading and trailing whitespace from the templates
trim = true
# postprocessors
postprocessors = [
    { pattern = '<REPO>', replace = "https://github.com/my-organization/my-repo" }, # replace repository URL
]

[git]
# parse the commits based on https://www.conventionalcommits.org
conventional_commits = true
# filter out the commits that are not conventional
filter_unconventional = true
# process each line of a commit as an individual commit
split_commits = false
# regex for preprocessing the commit messages
commit_preprocessors = [
    { pattern = '\((\w+\s)?#([0-9]+)\)', replace = "([#${2}](<REPO>/issues/${2}))"}, # replace issue numbers
]
# regex for parsing and grouping commits
commit_parsers = [
    { message = "^feat", group = "Features" },
    { message = "^fix", group = "Bug Fixes" },
    { message = "^doc", group = "Documentation" },
    { message = "^perf", group = "Performance" },
    { message = "^refactor", group = "Refactoring" },
    { message = "^style", group = "Style" },
    { message = "^revert", group = "Revert" },
    { message = "^test", group = "Tests" },
    { message = "^chore\\(version\\):", skip = true },
    { message = "^chore", group = "Miscellaneous Chores" },
    { body = ".*security", group = "Security" },
]
# filter out the commits that are not matched by commit parsers
filter_commits = false
# sort the tags topologically
topo_order = false
# sort the commits inside sections by oldest/newest order
sort_commits = "oldest"

Running Git-Cliff

Next, let’s do a dry run for the changelog generation. For example, generating changelog from version 0.9.2 to the latest commit.

git cliff v0.9.2..HEAD

The following output will be shown:

# Changelog

All notable changes to this project will be documented in this file. See [conventional commits](https://www.conventionalcommits.org/) for commit guidelines.

---
## [Unreleased](https://github.com/my-organization/my-repo/tree/HEAD)

### Bug Fixes

- handle invalid MIME format during image processing - ([f78c0d2](https://github.com/my-organization/my-repo/commit/f78c0d2de653ea46e13ea4c216b9ae951b339d50)) - Ryan Chang

### Lib

- bump webrick >= 1.8.2 ([#95](https://github.com/my-organization/my-repo/issues/95)) - ([9cc0e93](https://github.com/my-organization/my-repo/commit/9cc0e934c5cb64cee1ab3eedad2cd32e11c117de)) - Ryan Chang

---
## [1.0.0](https://github.com/my-organization/my-repo/compare/v0.9.2..v1.0.0) - 2024-08-18

### Refactoring

- use code generator only when activesupport >= 7.2 - ([95f9b41](https://github.com/my-organization/my-repo/commit/95f9b41de3107b685a1cd771061b209b79d21071)) - Ryan Chang

<!-- generated by git-cliff -->

To persist the changelog content, we need to add --ouput when running Git-Cliff command.

git cliff v1.0.0..HEAD --output CHANGELOG.md

Setting up the Workflow

Next, let’s create a GitHub Actions workflow file that handles both changelog generation and signed commits:

# changelog.yml
name: Generate Changelog

on:
  workflow_run:
    workflows: [CI]
    types: [completed]
    branches: [main]
  schedule:
    - cron: '0 0 * * *'  # Runs daily at midnight UTC

jobs:
  changelog:
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required to update CHANGELOG.md

    # Generate changelog for successful build only
    if: ${{ github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success' }}

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Required to check out full git history

      - uses: orhun/git-cliff-action@v4
        with:
          config: cliff.toml
          args: --output CHANGELOG.md
          
      - uses: ryancyq/github-signed-commit@v1
        env:
          GH_TOKEN: ${{ github.token }}
        with:
          files: CHANGELOG.md
          commit-message: "docs: update CHANGELOG.md"

How It Works

1. The workflow triggers when the CI workflow has completed on the main branch or runs daily at midnight UTC
2. Git-Cliff analyzes your git history and generates a formatted changelog based on conventional commits
3. github-signed-commit GitHub Action will commit CHANGELOG.md to the repository using GitHub Graphql API to guarantee verified commit on GitHub

Best Practices

1. Use conventional commits in your workflow:
   • feat: for new features
   • fix: for bug fixes
   • docs: for documentation changes
   • chore: for maintenance tasks
2. Review generated changelogs regularly:
   • Ensure proper categorization
   • Verify formatting
   • Check for sensitive information

Conclusion

Automating changelog generation with GitHub Actions streamlines your documentation process, combining Git-Cliff powerful parsing capabilities and signed commits ensures your changelog remains accurate, up-to-date, and trustworthy.

Remember to adjust the configuration to match your project’s needs and commit message patterns. This automation will save you time and ensure consistency across your project’s documentation.

However, to further improve our readers’ experience, users should be able to indicate their preference for light/dark mode across their favorite sites. As a user, I always welcome utilities to customize my reading experience for different site domains.

In this post, I’m going to share my experience of adding a light/dark theme switcher to a static site with minimal JavaScript involved.

Tailwind CSS Manual Dark Mode Toggle

First, we need to move away from the default dark mode configuration that uses the media strategy. As of this writing, Tailwind CSS 3.4.1 offers two other strategies: class and selector. Both will work in our case, but the official documentation recommends the selector strategy (Tailwind CSS manual dark mode).

Simple Light/Dark Theme Switcher

Let’s look at a simple light/dark theme switcher styled with Tailwind CSS. Similar to the JavaScript-free Responsive Navigation Menu guide, we’ll be using HTML <label> and <input> elements to keep track of the light/dark theme state.

Demo

HTML

<nav class="flex justify-between items-center bg-gray-100 dark:bg-gray-800">
  <a href="#" class="text-gray-800 dark:text-gray-200">Playground</a>
  <input id="theme-trigger" type="checkbox" class="hidden" />
  <label for="theme-trigger" class="rounded p-2 hover:bg-gray-200 dark:hover:bg-gray-700">
    <span class="sr-only">Switch to light / dark theme</span>
    <!-- Moon Icon -->
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" class="size-6 dark:hidden">
      <path d="M17.293 13.293A8 8 0 016.707 2.707a8.001 8.001 0 1010.586 10.586z" class="fill-gray-500"/>
    </svg>
    <!-- Sun Icon -->
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" class="size-6 hidden dark:block">
      <path d="M10 2a1 1 0 011 1v1a1 1 0 11-2 0V3a1 1 0 011-1zm4 8a4 4 0 11-8 0 4 4 0 018 0zm-.464 4.95l.707.707a1 1 0 001.414-1.414l-.707-.707a1 1 0 00-1.414 1.414zm2.12-10.607a1 1 0 010 1.414l-.706.707a1 1 0 11-1.414-1.414l.707-.707a1 1 0 011.414 0zM17 11a1 1 0 100-2h-1a1 1 0 100 2h1zm-7 4a1 1 0 011 1v1a1 1 0 11-2 0v-1a1 1 0 011-1zM5.05 6.464A1 1 0 106.465 5.05l-.708-.707a1 1 0 00-1.414 1.414l.707.707zm1.414 8.486l-.707.707a1 1 0 01-1.414-1.414l.707-.707a1 1 0 011.414 1.414zM4 11a1 1 0 100-2H3a1 1 0 000 2h1z"
        fill-rule="evenodd"
        clip-rule="evenodd"
        class="fill-gray-400"
      />
    </svg>
  </label>
</nav>

Store Theme Switcher State

Next, let’s use the localStorage API to keep track of the state when a user toggles between light and dark themes.

Javascript

const opted = 'color-theme' in localStorage
const optedDark = localStorage.getItem('color-theme') === 'dark'
const preferDark = window.matchMedia('(prefers-color-scheme: dark)').matches
const shouldBeDark = optedDark || (!opted && preferDark)

function toggleTheme(forceDark) {
  document.documentElement.classList.toggle('dark', forceDark)
  localStorage.setItem('color-theme', forceDark ? 'dark' : 'light')
}

toggleTheme(shouldBeDark)

To avoid theme switching happening after DOM rendering, we could place the script in the HTML head section instead.

HTML

<head>
  <meta charset="utf-8">
  <!-- more metadata -->

  <script type="text/javascript">
    // .. toggle theme script
  </script>
</head>

Register User Interaction with Theme Switcher

Once the default or user-selected theme has been initialized, we can register an event handler to the theme switcher and allow users to toggle the theme freely.

Javascript

const trigger = document.getElementById('theme-trigger');
trigger.checked = document.documentElement.classList.contains('dark') // assign initial state to the trigger element
trigger.addEventListener('change', toggleTheme)

We’ll also need to modify the toggleTheme function to handle the change event.

function toggleTheme(event) {
  const forceDark = event.target instanceof HTMLInputElement ? event.target.checked : !!event
  document.documentElement.classList.toggle('dark', forceDark)
  localStorage.setItem('color-theme', forceDark ? 'dark' : 'light')
}

The event handler registration should only be executed once (e.g., when the HTML document is loaded/ready). An easy way to achieve this is to append a <script> tag at the end of the document’s <body> tag.

HTML

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <script type="text/javascript">
      // toggle theme
    </script>
  </head>
  <body>
    <script type="text/javascript">
      // register event handler
    </script>
  </body>
</html>

And that’s all you need to create a light/dark theme switcher for your static site.

If you don’t already have a working setup for Ruby code coverage, I recommend checking out my Ruby Code Coverage Setup Guide, where I explain how to configure coverage reports for different dependencies and runtimes via test runners. You can also find the example at ryancyq/ruby-code-coverage.

Prerequisites

These are the tools being used:

• CodeCov : A code coverage reporting and tracking tool.
• GitHub Actions : A CI/CD platform integrated with GitHub.

Create a GitHub Actions Workflow

Let’s create a GitHub Actions workflow for code coverage analysis and run the same job for different Ruby versions. This will be done by leveraging GitHub Actions matrix strategies.

# coverage.yml
jobs:
  coverage:
    name: "Ruby ${{ matrix.ruby-version }}"
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        ruby-version: 
          - "2.7"
          - "3.0"
          - "3.1"
          - "3.2"
          - "3.3"
          - "head"
    
    steps:
      - uses: actions/checkout@v4

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: ${{ matrix.ruby-version }}
          rubygems: 3.4.22 # last version to support Ruby 2.7

Next, we need to install the gems required for generating the coverage report as described in Ruby Code Coverage setup guide.

# coverage.yml
jobs:
  coverage:
      # .. more

      - run: gem install rake rspec simplecov simplecov-html simplecov-cobertura
      - run: rake coverage:run

      - run: sudo apt install tree
      - run: tree -a coverage

      - uses: actions/upload-artifact@v4
        with:
          name: "coverage-ruby-${{ matrix.ruby-version }}"
          path: coverage/ruby-*
          include-hidden-files: true
          retention-days: 1

The tree command is included in the example for troubleshooting purposes. In the case of Ruby 3.3, we should see the following output after executing the tree command:

coverage
└── ruby-3.3.5
    ├── .last_run.json
    ├── .resultset.json
    ├── .resultset.json.lock
    └── coverage.xml

1 directory, 4 files

The coverage result from each Ruby version will be uploaded to GitHub Actions Artifacts.

Collate Coverage Reports from Test Runners

Next, we need to add another report job to collate the coverage results into a single coverage result.

# coverage.yml
jobs:
  # .. more

  report:
    name: "Report to CodeCov"
    needs: [coverage]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          pattern: coverage-ruby-*
          path: coverage-results
          merge-multiple: true

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: "3"

      - run: gem install rake rspec simplecov simplecov-html simplecov-cobertura
      - run: rake coverage:report
        env:
          COV_DIR: coverage-results

      - run: sudo apt install tree
      - run: tree -a coverage-results
      - run: tree -a coverage

The outputs from the tree commands above should look something like:

tree -a coverage-results

coverage-results
├── ruby-2.7.8
│   ├── .last_run.json
│   ├── .resultset.json
│   ├── .resultset.json.lock
│   └── coverage.xml
├── ruby-3.0.7
│   ├── .last_run.json
│   ├── .resultset.json
│   ├── .resultset.json.lock
│   └── coverage.xml
├── ruby-3.1.6
│   ├── .last_run.json
│   ├── .resultset.json
│   ├── .resultset.json.lock
│   └── coverage.xml
├── ruby-3.2.5
│   ├── .last_run.json
│   ├── .resultset.json
│   ├── .resultset.json.lock
│   └── coverage.xml
├── ruby-3.3.5
│   ├── .last_run.json
│   ├── .resultset.json
│   ├── .resultset.json.lock
│   └── coverage.xml
└── ruby-3.4.0
    ├── .last_run.json
    ├── .resultset.json
    ├── .resultset.json.lock
    └── coverage.xml

6 directories, 24 files

tree -a coverage

coverage
├── .last_run.json
├── .resultset.json
├── .resultset.json.lock
└── coverage.xml

0 directories, 4 files

Report to CodeCov

In the next step, we will pass the coverage directory (which contains the collated coverage result) to CodeCov Action.

# coverage.yml
jobs:
  # .. more

  report:
    steps:
        # .. more

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          directory: coverage
          token: ${{ secrets.CODECOV_TOKEN }}
          fail_ci_if_error: true

Report to CodeCov with Flags

Alternatively, if you want to leverage CodeCov Flags to have a better overview of the coverage result for each Ruby version, we could skip coverage result collation and upload individual coverage results to CodeCov with the corresponding flags.

# coverage.yml
jobs:
  # .. more

  report:
    name: "Report to CodeCov"
    needs: [coverage]
    runs-on: ubuntu-latest
    strategy:
      fail-fast: false
      matrix:
        ruby-version: 
          - "2.7"
          - "3.0"
          - "3.1"
          - "3.2"
          - "3.3"
          - "head"

    steps:
      - uses: actions/checkout@v4

      - uses: actions/download-artifact@v4
        with:
          pattern: "coverage-ruby-${{ matrix.ruby-version }}*"
          path: coverage

      - run: sudo apt install tree
      - run: tree -a coverage

      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v4
        with:
          directory: coverage
          token: ${{ secrets.CODECOV_TOKEN }}
          flags: "ruby-${{ matrix.ruby-version }}"
          fail_ci_if_error: true

In the modified report job, we’ve removed the need for ruby-setup to collate coverage results, and artifacts are now downloaded one at a time.

The coverage report for each Ruby version remains around 91% due to the if-else statement on RUBY_VERSION.

However, the overall code coverage stays at 100% as the result of merging the individual coverage reports.

Most of the time, testing is limited to the current production environment or major updates in OS or runtime images. However, things are slightly different when it comes to Ruby libraries or standalone applications.

In this post, I’ll share my experience maintaining a Ruby library across different Ruby versions, gem dependencies, and OS versions. You can also find the example at ryancyq/ruby-code-coverage.

Prerequisites

These are the libraries being used in this project:

• SimpleCov : A code coverage analysis tool for Ruby
• RSpec : A behavior-driven development framework for Ruby
• Rake : A Ruby build utility similar to Make

Code using different Ruby APIs

For example, Ruby 3.1 introduced an improvement to the File#dirname method, allowing for parent directory retrieval with an optional level parameter. For more details, you can check the issue tracker at Ruby Issue 12194.

# lib/config.rb
class Config
  ROOT = if RUBY_VERSION >= "3.1"
           File.dirname(__FILE__, 2).freeze
         else
           File.expand_path(File.join(File.dirname(__FILE__), "..")).freeze
         end
end

Write a Test with RSpec

Now write a RSpec test for Config::ROOT

# spec/config_spec.rb
require "pathname"
require_relative "../lib/config"
RSpec.describe Config do
  describe "ROOT" do
    subject { Config::ROOT }

    let(:root_dir) { Pathname.new(__dir__).parent.to_s }

    it { is_expected.to eq root_dir }
  end
end

RSpec Execution Approaches

There are two ways to execute RSpec commands:

1. run rspec with CLI arguments. e.g. rspec --require spec_helper --format documentation.

2. run the RSpec rake task with preconfigured setup.

   RSpec rake task will spawn child process to execute RSpec CLI with arguments.

Create RSpec Rake Task

Let’s add an RSpec rake task to simplify the command to run tests. This will become handy for code coverage later on.

# tasks/rspec.rake
require "rspec/core/rake_task"
RSpec::Core::RakeTask.new(:spec) do |config|
  config.rspec_opts = "--format documentation"
end

# Rakefile
Dir[File.expand_path("tasks/*.rake", __dir__)].each { |task| load task }

Now, run rake --tasks to see the rake tasks that have been configured.

rake spec             # Run RSpec code examples

When running the command rake spec, we will see the following output.

Config
  ROOT
    is expected to eq "/path/to/root"

Finished in 0.00058 seconds (files took 0.05219 seconds to load)
1 example, 0 failures

Configure Code Coverage when Running RSpec

With RSpec set up sucessfully, we can proceed with code coverage configuration. For this step, we will use the centeralized configuration file, .simplecov to initialize SimpleCov whenever require 'simplecov' statement is called.

Using the following configuration, the coverage report (ruby-X.X.X folder) will be generated in the folder specified by ENV['COV_DIR'] or default to coverage folder in the current working directory.

# .simplecov
SimpleCov.configure do
  enable_coverage :branch
  command_name "ruby-#{RUBY_VERSION}"
  coverage_dir File.join(ENV.fetch("COV_DIR", "coverage"), command_name)

  if ENV["CI"]
    require "simplecov-cobertura"
    formatter SimpleCov::Formatter::CoberturaFormatter
  end
end

Now, let’s create coverage.rake to run code coverage analysis through RSpec.

# tasks/coverage.rake
namespace :coverage do
  desc "Run coverage with spec"
  task :run do
    Rake::Task[:spec].invoke(coverage: true)
  end
end

We also need to modify RSpec rake task to start SimpleCov during RSpec execution.

# tasks/rspec.rake
require "rspec/core/rake_task"
RSpec::Core::RakeTask.new(:spec, [:coverage]) do |config, args|
  config.ruby_opts = "-r./.simplecov_spawn" if args[:coverage]
  config.rspec_opts = "--format documentation"
end

Following the SimpleCov Spawn Subprocesses Guide to start SimpleCov for spawned subprocesses, we’ll skip the SimpleCov.at_fork.call(Process.pid) step, as the additional fork behavior isn’t needed in this case.

# .simplecov_spawn.rb
require "simplecov"
SimpleCov.start

Now, run rake --tasks to view the updated rake tasks:

rake coverage:run     # Run coverage with spec
rake spec[coverage]   # Run RSpec code examples

When running rake coverage:run with RUBY_VERSION set to 3.3.4, the output will be:

Coverage report generated for ruby-3.3.4 to /path/to/root/coverage/ruby-3.3.4.
Line Coverage: 90.91% (10 / 11)
Branch Coverage: 50.0% (1 / 2)

Similarly, with RUBY_VERSION set to 3.0.7, you’ll see:

Coverage report generated for ruby-3.0.7 to /path/to/root/coverage/ruby-3.0.7.
Line Coverage: 90.91% (10 / 11)
Branch Coverage: 50.0% (1 / 2)

However, despite the identical output, the underlying results are completely different.

Collate Multiple Reports into a Unified Coverage Report

Finally, we will add another rake task coverage:report to collate the coverage results into a single coverage report.

# tasks/coverage.rake
namespace :coverage do
  desc "Run coverage with spec"
  task :run do
    Rake::Task[:spec].invoke(coverage: true)
  end

  desc "Collate coverage results generated by different test runners"
  task :report do
    require "simplecov"
    coverage_dir = File.join(File.dirname(SimpleCov.coverage_dir), "ruby-*")
    coverage_results = Dir[File.join(coverage_dir, ".resultset.json")]

    raise <<~MSG if coverage_results.empty?
      Coverage results not found, searched in:
      #{Dir[coverage_dir].map { |dir| "  - #{dir}" }.join("\n")}
    MSG

    SimpleCov.collate(coverage_results) do
      coverage_dir "coverage"
    end
  end
end

desc "Run coverage analysis and collate coverage results"
task coverage: ["coverage:run", "coverage:report"]

Now, run rake --tasks to view the updated rake tasks:

rake coverage         # Run coverage analysis and collate coverage results
rake coverage:report  # Collate coverage results generated by different test runners
rake coverage:run     # Run coverage with spec
rake spec[coverage]   # Run RSpec code examples

When running rake coverage:report, the output will be:

Coverage report generated for ruby-3.0.7, ruby-3.3.4 to /path/to/root/coverage.
Line Coverage: 100.0% (11 / 11)
Branch Coverage: 100.0% (2 / 2)

The final project structure should look like this:

├── coverage
│   ├── ruby-3.0.7
│   │   ├── assets
│   │   ├── .resultset.json
│   │   ├── index.html
│   │   └── coverage.xml # when CoberturaFormatter is enabled
│   ├── ruby-3.3.4
│   │   ├── assets
│   │   ├── .resultset.json
│   │   ├── index.html
│   │   └── coverage.xml # when CoberturaFormatter is enabled
│   ├── assets
│   ├── .resultset.json
│   ├── index.html
│   └── coverage.xml # when CoberturaFormatter is enabled
├── lib
│   └── config.rb
├── spec
│   └── config_spec.rb
├── tasks
│   ├── coverage.rake
│   └── rspec.rake
├── .simplecov
├── .simplecov_spawn.rb
└── Rakefile

To create responsive navigation menus, it often involves using a “hamburger” menu for small screen widths and a regular navbar for larger screens. The conventional way of achieving a collapsible navigation menu is by attaching a JavaScript event handler to the hamburger menu to toggle the menu’s visibility on the click event.

However, we can achieve the same behavior by leveraging native HTML.

Simple Navigation Menu

Let’s look at a simple navigation menu styled with Tailwind CSS.

Demo

HTML

<nav class="flex flex-wrap justify-between items-center bg-gray-50 dark:bg-gray-800">
  <a href="#">Playground</a>
  <ul class="inline-flex gap-x-2">
    <li><a href="#" class="hover:underline">Home</a></li>
    <li><a href="#" class="hover:underline">About</a></li>
    <li><a href="#" class="hover:underline">Contact</a></li>
  </ul>
</nav>

Responsive Navigation Menu

Next, let’s add the hamburger menu for screens smaller than md using an HTML <button>.

Demo

HTML

<nav class="flex flex-wrap justify-between items-center bg-gray-50 dark:bg-gray-800">
  <a href="#">Playground</a>
  <div class="inline-flex gap-x-2 items-center">
    <button class="md:hidden rounded p-2 hover:bg-gray-100 dark:hover:bg-gray-700">
      <svg class="size-5" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 17 14">
          <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M1 1h15M1 7h15M1 13h15"/>
      </svg>
    </button>
    <ul class="flex-col gap-y-2 hidden md:inline-flex md:flex-row md:gap-x-2">
      <li><a href="#" class="hover:underline">Home</a></li>
      <li><a href="#" class="hover:underline">About</a></li>
      <li><a href="#" class="hover:underline">Contact</a></li>
    </ul>
  </div>
</nav>

Usually, handling the button click event to toggle menu visibility requires JavaScript. Here, we are going to use HTML <label> and <input> elements to replace the <button>. According to HTML label element definition, the <label> element is designed to pass user interaction events to the associated <input> element via a matching id. We can utilize this design principle by placing the <input> tag anywhere in the HTML body.

Demo

HTML

<nav class="flex flex-wrap justify-between items-center bg-gray-50 dark:bg-gray-800">
  <a href="#">Playground</a>
  <input id="navbar-trigger" type="checkbox" class="hidden"/>
  <label for="navbar-trigger" class="md:hidden rounded p-2 hover:bg-gray-100 dark:hover:bg-gray-700">
    <svg class="size-5" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 17 14">
        <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M1 1h15M1 7h15M1 13h15"/>
    </svg>
  </label>
  <ul class="flex-col gap-y-2 hidden md:inline-flex md:flex-row md:gap-x-2">
    <li><a href="#" class="hover:underline">Home</a></li>
    <li><a href="#" class="hover:underline">About</a></li>
    <li><a href="#" class="hover:underline">Contact</a></li>
  </ul>
</nav>

Tailwind CSS Peer Modifier

Next, we are going to use a CSS attribute selector on siblings to toggle menu visibility. This is where Tailwind CSS peer-{modifier} comes in handy.

This is the reason behind placing the <input> outside of the <label> to achieve the following hierarchy:

<input id="navbar-trigger"/>
<label for="navbar-trigger"></label>
<ul>
  <li>Home</li>
  <li>About</li>
  <li>Contact</li>
</ul>

Using peer-{modifiers}, we can now hide the <input> and add the peer/hamburger CSS class to allow the sibling <ul> CSS classes to bind with the <input> using peer-checked/hamburger:inline-flex.

Demo

HTML

<!-- adding flex-wrap to ensure expanded menu will be wrapped -->
<nav class="flex flex-wrap justify-between items-center bg-gray-50 dark:bg-gray-800">
  <a href="#">Playground</a>
  <input id="navbar-trigger" type="checkbox" class="hidden peer/hamburger"/>
  <label for="navbar-trigger" class="md:hidden rounded p-2 hover:bg-gray-100 dark:hover:bg-gray-700">
    <svg class="size-5" aria-hidden="true" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 17 14">
        <path stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M1 1h15M1 7h15M1 13h15"/>
    </svg>
  </label>
  <!-- There are 2 styles for the <ul> -->
  <!-- Full width with border menu (< md): -->
  <!-- flex-col gap-y-2 mt-2 px-4 py-2 rounded-lg bg-gray-200 w-full hidden peer-checked/hamburger:inline-flex -->
  <!-- Auto-sized and borderless menu (>= md): -->
  <!-- md:w-auto md:inline-flex md:flex-row md:gap-x-2 md:mt-0 md:p-0 md:rounded-none md:bg-transparent -->
  <ul class="flex-col gap-y-2 mt-2 px-4 py-2 rounded-lg bg-gray-200 dark:bg-gray-700 w-full hidden peer-checked/hamburger:inline-flex md:w-auto md:inline-flex md:flex-row md:gap-x-2 md:mt-0 md:p-0 md:rounded-none md:bg-transparent">
    <li><a href="#" class="hover:underline">Home</a></li>
    <li><a href="#" class="hover:underline">About</a></li>
    <li><a href="#" class="hover:underline">Contact</a></li>
  </ul>
</nav>

And with that, you’ve created a fully functional, responsive navigation menu using Tailwind CSS, completely free of JavaScript, making it an ideal solution for lightweight, static websites.

For personal blogs, most folks deploy from the main branch with the root folder, while project websites might deploy from a separate branch like gh-pages with a doc folder in the root. Check out GitHub Pages deployment for more details.

Once you’ve got the basic setup, you might want to add some cool 3rd party libraries to enhance your website. GitHub Pages is powered by Jekyll and has a safelist of supported Ruby gems. See GitHub Pages dependencies for the list.

At the moment, GitHub Pages supports only up to Jekyll 3.x, but there are plenty of reasons to upgrade to Jekyll 4.x. Plus, there are many awesome 3rd party libraries that aren’t on the safelist.

Deploy Custom Jekyll Build Pipeline

To get around this, we can set up a GitHub Actions workflow to bypass the default deployment pipeline offered by GitHub Pages. The official Jekyll documentation on GitHub Actions explains the benefits of using a GitHub Actions workflow.

This way, we can add dependencies like Tailwind CSS, a super popular utility-first CSS framework that makes your website look amazing with minimal effort.

Prerequisites

Make sure you have a working Jekyll + Tailwind CSS setup on your machine. See my post on Jekyll and Tailwind CSS setup guide.

Step 1: Ensure Gemfile.lock Supports the OS on GitHub Actions

We usually use the ubuntu OS image in GitHub Actions. To make sure bundler can install the dependencies with ubuntu, your Gemfile.lock should have x86_64-linux under PLATFORMS.

If not, you can add it with this command:

  bundle lock --add-platform x86_64-linux

Step 2: Select Page Deployment Approach

Following the Jekyll documentation on GitHub Actions, your configuration will look something like this:

Click on Configure under GitHub Pages Jekyll workflow.

Step 3: Create a GitHub Actions Workflow

When creating the workflow, you’ll need to tweak the default template a bit:

# jekyll.yml
name: Deploy Jekyll site to Pages
# ... more

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1 # replaced with major version to get latest updates
        with:
          ruby-version: "3.3" # or create a .ruby-version
          bundler-cache: true
      
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v5

      - name: Build with Jekyll
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: production

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

For reference, see the official actions/build-jekyll-for-github-pages.

Step 4: Add Node.js Setup for TailwindCSS

Include Node.js setup and install JavaScript dependencies with:

# jekyll.yml
name: Deploy Jekyll site to Pages
# ... more

jobs:
  build:
    steps:
      # ... more

      - name: Setup Ruby
        # ... more

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 20 # any node version would do, preferably an LTS version
      - name: Install Tailwind CSS dependencies
        run: npm install

      - name: Setup Pages
        # ... more

Step 5: Push and Deploy

After all these steps, you should see a successful build like this:

And that’s it! You’ve now set up a Jekyll site with Tailwind CSS and deployed it using GitHub Actions. With this setup, you can take full advantage of Jekyll 4.x and any other dependencies you want to include!

One huge advantage of using Jekyll is the free hosting you get with GitHub Pages for public repositories. If you’re cool with this setup, GitHub Pages is a no-brainer.

Check out my post on Deploy Jekyll to GitHub Pages with Tailwind CSS for more details on deploying a custom Jekyll build to GitHub Pages.

Prerequisites

Make sure you have the necessary dependencies installed on your machine.

Step 1: Install Ruby and Jekyll

First things first, you need to install Ruby using rbenv (recommended) and then get the Jekyll gem. Follow rbenv installation guide to have it installed on your machine.

# Install rbenv and Ruby
rbenv install 3.3.1
rbenv global 3.3.1

# Install Jekyll, Bundler
gem install jekyll bundler

Step 2: Create a New Jekyll Site

Now, let’s create a new Jekyll site from scratch.

jekyll new my-personal-blog --blank
cd my-personal-blog

Optionally, you can create a .ruby-version file for the Ruby version you have installed.

echo "3.3.1" > .ruby-version

Step 3: Install jekyll-postcss dependency for Ruby

Add jekyll-postcss to your Gemfile.

echo "gem 'jekyll-postcss', '~> 0.5.0', group: :jekyll_plugins" >> Gemfile
bundle install

Then configure jekyll-postcss by adding the following to your Jekyll _config.yml.

# _config.yml
plugins:
  - jekyll-postcss

postcss:
  cache: false # disable cache in favor of Tailwind CSS JIT engine

Tailwind CSS 3.x has the Just-In-Time (JIT) engine enabled by default. For more details, refer to the Tailwind CSS JIT Migration guide.

Step 4: Install Node and Tailwind CSS v3

Next, install Node.js using nvm (recommended). Follow nvm installation guide to get it installed.

# Install Node.js LTS version
nvm install --lts

Then install Tailwind CSS, PostCSS, cssnano, and autoprefixer as dev dependencies.

# Initialize npm and install dependencies
npm init -y
npm install --save-dev tailwindcss postcss cssnano autoprefixer

• Tailwind CSS : A utility-first CSS framework for rapid UI development.
• PostCSS : A tool for transforming CSS with JavaScript plugins.
• cssnano : A PostCSS plugin to minify the final CSS output for better performance.
• autoprefixer : A PostCSS plugin to add vendor prefixes to CSS rules for better browser support.

Step 5: Create PostCSS Config

Now, create a postcss.config.js file with the following content:

// postcss.config.js
module.exports = {
  plugins: [
    require('tailwindcss'),
    require('autoprefixer'),
    ...(process.env.JEKYLL_ENV == 'production'
      ? [require('cssnano')({ preset: 'default' })]
      : [])
  ]
}

Step 6: Create Tailwind v3 Config

Specify the content (Markdown and HTML files) for Tailwind CSS to detect the usage of CSS classes. Only the CSS classes that are used will be compiled into the output CSS file (assets/css/main.css).

// tailwind.config.js
module.exports = {
  content: [
    './_drafts/**/*.html',
    './_includes/**/*.html',
    './_layouts/**/*.html',
    './_posts/*.md',
    './*.md',
    './*.html',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Step 7: Remove Jekyll SASS

Rename the default scss file provided by Jekyll at assets/css/main.scss to assets/css/main.css. Also, change the content to the following:

/* assets/css/main.css */
---
---

@tailwind base;
@tailwind components;
@tailwind utilities;

Remove the _sass folder in the root directory as well to entirely get rid of the SASS setup.

Step 8: Start the Jekyll Server

Finally, start the Jekyll server with live reload enabled.

bundle exec jekyll serve --livereload

By following these steps, you’ll have a Jekyll site styled with Tailwind CSS at localhost:4000.

With --livereload, you can head over to the root directory and create any md or html files and start using Tailwind CSS classes like text-blue-500 to see the changes reflected in real-time.

Enjoy building your static site!