whiteglass: a minimal Jekyll theme that needs CI for archives

The gem carries the theme, not the site

whiteglass ships as a Ruby gem called jekyll-whiteglass, and hooking it into a site takes two edits. The first is a single line in the Gemfile, the second is a theme key in _config.yml, and then the dependencies are installed. The Gemfile line looks like this, and it is the only Ruby you need to add:

gem "jekyll-whiteglass"

The config file needs a single theme key:

theme: jekyll-whiteglass

With both in place, the dependency install is a one-liner:

bundle

If you would rather install the gem on its own, the theme also documents a direct gem install command. The theme describes itself as a "Minimal, responsive Jekyll theme for hackers", and the repository layout supports that claim: the top level holds _includes, _layouts, _sass, _data, assets, a handful of pages, and a gemspec, with no separate build tooling of its own. That shape is the main reason to consider it. A theme this small can be read end to end before you commit to it. The tradeoff is that there is no settings file to hide behind, so every change you want is a file you copy into your own site. A separate template repository, yous/whiteglass-template, is offered as a starting point where GitHub Actions builds the site after each push.

The manual path downloads seven files with curl

For people who do not want to start from the template repository, the project documents a manual route that starts from a plain Jekyll site and then copies the theme's pages in. Generating the site and entering it is the first step, and the theme gem and its plugins go into the Gemfile and _config.yml. What follows is the part people tend to skip: the site has no index page of its own yet, so the theme's index.html, about.md, archives.md, feed.xml, robots.txt and the two data files have to be pulled down into the new site. The commands given for that step use curl to fetch the files from the theme's master branch, with a second command that creates the _data directory as it goes. The permalink style, the pagination path and the archive settings are fixed in the same configuration block, so the copy step and the config step have to agree with each other or the generated URLs will not match what the theme's own links expect. The finished site is served locally on port 4000.

jekyll-archives is the reason GitHub Pages is not enough

The theme relies on the jekyll-archives gem to build category and tag archive pages, and it is stated plainly that this gem is not supported by GitHub Pages. The consequence is concrete: on a plain GitHub Pages build the theme still renders, but the archive pages that depend on the plugin will not be produced. The recommended path is to use Travis CI or another CI service if you want the full feature set, and the project includes a .travis.yml with a target-branch setting and an on.branch setting, both meant to be edited. Deployment then requires a personal access token with public_repo or repo permission, exposed to the CI service as the environment variable GITHUB_TOKEN. The design decision here trades a one-click publish button for plugin freedom, and the cost is worth naming plainly: token management and CI configuration become part of publishing your posts, which is a real operational difference from themes that work out of the box on Pages.

Overrides work by shadowing files in the site root

The customization model is the part of whiteglass that is genuinely pleasant to use, and it is worth understanding precisely. Jekyll resolves theme files by looking in the site source first, so any file you place at the corresponding path in your own repository takes precedence over the copy inside the gem. To change the footer, for example, you create an _includes directory in your site, copy _includes/footer_content.html out of the jekyll-whiteglass gem folder into it, and then edit that copy. Favicons go the same way, as link elements written into _includes/head_custom.html:

<link rel="icon" type="image/x-icon" href="{{ "/favicon.ico" | relative_url }}">
<link rel="apple-touch-icon" href="{{ "/apple-touch-icon.png" | relative_url }}">
<link rel="apple-touch-icon" sizes="76x76" href="{{ "/apple-touch-icon-76x76.png" | relative_url }}">
<link rel="apple-touch-icon" sizes="120x120" href="{{ "/apple-touch-icon-120x120.png" | relative_url }}">
<link rel="apple-touch-icon" sizes="152x152" href="{{ "/apple-touch-icon-152x152.png" | relative_url }}">
<link rel="apple-touch-icon" sizes="180x180" href="{{ "/apple-touch-icon-180x180.png" | relative_url }}">

A customization is therefore a real file in your own repository, reviewable in a diff and revertible with a commit, rather than a setting a theme update might reinterpret. The cost is duplication: your site now carries a copy of a theme file, and when the theme changes that file you are the one reconciling the difference.

main.scss offers three different override routes

The stylesheet gets special treatment because the default CSS lives inside the gem at assets/main.scss, and three separate takeover methods are listed. The first is to create a new assets/main.scss at the site source, add frontmatter dashes, import the theme with the whiteglass import, and add your own rules underneath. The second is to copy the contents of the theme's assets/main.scss into your own file and edit it directly. The third is to copy the whole assets folder out of the local gem installation, whose path you can obtain with bundle show jekyll-whiteglass, and change whatever values you want inside it. These are not equivalent in terms of future upgrades. The first keeps a live link to the theme's variables and loses it only if the theme renames them. The second and third freeze a copy at a point in time, which turns an upgrade into a manual merge rather than a no-op.

Locale strings live in _data/i18n.yml and the language is per page

Translation is split across two mechanisms, and the split is easy to miss. The primary language of the site is declared with the lang configuration key, where en-US selects the United States flavor of English, en-GB the United Kingdom one, and the shorter en form is also accepted. Individual posts can override that by setting a lang attribute in their own frontmatter:

layout: post
title: "안녕하세요"
lang: ko

Fixed interface strings, including the date format, live in the separate _data/i18n.yml file, and contributors are asked to open a pull request when a language is not yet included. Because the interface strings are data rather than templates, a translator works on a YAML file instead of on Liquid markup, which is a reasonable split. It does mean a site needing an unlisted language is waiting on a pull request to the theme rather than being able to define the strings locally, and the navigation labels come from a sibling file, _data/navigation.yml, which has to be copied over separately from the gem.

A theme-free Jekyll site is the honest alternative

The manual setup path begins by generating a new Jekyll blog with the skip-bundle flag, which produces a site with no theme applied at all. That is a genuine alternative worth naming, and its difference in approach is not subtle. A generated site has no archive pages to lose, so it publishes on GitHub Pages without a CI service or a token. What you give up is the layout set, the stylesheet, the icon hooks and the multilingual interface strings that whiteglass ships, and you end up writing those pieces yourself. Between the two, a solo writer who only wants a handful of posts and no archives may find the unthemed site less work in total. A writer who wants categories, tags, an archive index, a feed and a consistent look is better served by whiteglass, and should accept the CI arrangement as part of the price.

Commits continued after the last tagged release

The maintenance picture is mixed and should be read carefully. The repository is not archived, and the last push was on 2026-07-21, so work on the theme has continued well past the most recent release. The tagged releases tell a different story: the newest are v1.11.7 on 2024-10-15, v1.11.6 on 2024-10-13 and v1.11.5 on 2024-10-13, three tags in three days, and then a long gap with no further release. The upgrade notes cover migration from versions below 1.9.1, where the only required step is copying _data/i18n.yml from the theme, which suggests the breaking changes of that era were concentrated in the data file rather than in the layouts. For an adopter, the practical question is what a given version contains, since a site pinning an old tag is not receiving the newer commits. Read CHANGELOG.md and the tags before choosing which version to pin, and expect to reconcile your overridden files when the version changes.

Editorial conclusion

whiteglass fits a writer who wants a quiet blog and is willing to read the theme source and shadow files in the site root to change it. It does not fit a team that expects GitHub Pages push and forget publishing, because the category and tag archive pages require an external CI service and a deploy token. Before adopting it, check the plugins listed in your _config.yml against what GitHub Pages will run for you, confirm that the strings in _data/i18n.yml cover the languages you need, and read CHANGELOG.md before pinning a version, since the last push was on 2026-07-21 while the most recent tagged release is v1.11.7 from 2024-10-15.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. yous/whiteglass on GitHub