featherweight — Jekyll Starter Template

SHA-256: b84c569e287a617ef747037004b22c18c30016112c308358c8962826e71e243a

2026-10-03T00:17:35.783Z

`Featherweight` is an ultra-lightweight Jekyll theme, aiming to minimise bandwidth usage and deliver a bare-bones experience (page sizes of ~1kb). 

[![Gem Version](https://img.shields.io/gem/v/featherweight?style=flat-square)][ruby-gems]

[ruby-gems]: https://rubygems.org/gems/featherweight

#### Building on GitHub

If you're using this site on GitHub pages, the built-in build action won't run gems outside of the [supported plugins list](https://pages.github.com/versions/).

To enable these gems, use the `build_and_deploy.yml` action under `.github/workflows` to automatically build your site on pushes, which circumvents this restriction while still hosting using GitHub pages (as advised by [Jekyll](https://jekyllrb.com/docs/continuous-integration/github-actions/)).

The workflow pushes the build to `gh-pages` branch, so make sure this exists and your GitHub page is set to deploy from this branch.

#### Featherweight as a remote theme

`Featherweight` can be used as a remote theme, enabling integration into existing projects.
We recommend using the same action setup as described above, but using the [Cutwell/jekyll-build-action](https://github.com/Cutwell/jekyll-build-action) action, to support the theme gem's dependence on Ruby 3.0.0.

Copy the `_config.yml` file into your repository root, adding the following markup to specify the theme:
```yml
theme: featherweight
```

Also create a `Gemfile` file in the repository root, with the following content:
```Gemfile
source "https://rubygems.org"

gem 'featherweight', '~> 0.7.6'
```

Additionally, copy the `index.md` and `_includes/contact.md` files, and customise them to personalise your site.

With this setup, the theme will now build and install. See [Cutwell/cutwell.github.io](https://github.com/Cutwell/cutwell.github.io) for an example of this theme being used remotely.

#### Writing blog posts

Create a blank `.md` file in `_pages/`, and add:
```
---
layout: post
title: My blog post.
description: A description of the post, used for metadata.
image: (optional) an image to display when linking to the post on e.g.: Twitter or Facebook
---
```

Write your blog post in GitHub-flavoured-markdown below the metadata.

When naming blog post files, use the `YYYY-MM-DD-title.md` convention, or else your post won't appear in the blog post list. Read the [Jekyll docs](https://jekyllrb.com/docs/posts/).

#### Cheatsheet

|||
|:--:|:--:|
| _Config_ | Update site URL and othe default options using `_config.yml`. |
| _Homepage_ | Customise your homepage by editing the `index.md` file. |
| _Social media_ | Update your contact links for your homepage and post footer (optional) by editing `_includes_/contact.md` |
| _RSS_ | The RSS feed can be found at <https://yourgithubusername.github.io/feed>. |
| _Sitemap_ | The sitemap can be found at <https://yourgithubusername.github.io/sitemap>. |
| _Quickstart_ | Test your website locally by following the [Jekyll quickstart guide](https://jekyllrb.com/docs/). |
| _gzip compression_ | Files are compressed using [Zopfli](https://github.com/philnash/jekyll-zopfli) compression. GitHub GZip's files automatically before serving, but we can use more aggressive pre-compression to achieve better compression, and avoid server overhead to compress on-the-fly. Support seems to vary between browsers, and some will fallback to `.html`. |
| _Brotli compression_ | We also compress files using Google's [Brotli](https://en.wikipedia.org/wiki/Brotli) algorithm. We serve `.gz` and `.html` as fallback, although `.br` [has good support](https://caniuse.com/brotli). |
| _Page reflow protection_ | To prevent page-reflow whilst lazy-loading images, we set image height and width using `Cutwell/jekyll-anti-image-reflow` gem plugin. Note it will not override existing styling to loading, width or height attributes. |

#### Cosmetics
`Featherweight` allows you to enable numerous cosmetic upgrades for your site. Toggle these options in the `compression` settings in `_config.yml`. These cosmetics all add to the total page weight, but can significantly improve the UX.

Many of these are entirely optional settings. If you're looking to create a truly minimal webpage, read the comments inside `_config.yml`.

|||
|:--:|:--:|
| _SEO_ | Enabling search engine optimisations will add metadata for search engines and sharing on social media. |
| _Reading time_ | To display an estimated reading time for blog posts. |
| _Load time_ | Show off your page load times in the page footer. (Requires JS) |
| _Page size_ | Report the webpage size in bytes, also displayed in the page footer. (Requires JS) |
| _Social media footer_ | Display social media links below blog posts. |
| _Blog list_ | Toggle the display of your blog list on the homepage. |
| _CSS_ | Add some basic styling, based on [58 bytes of CSS to look great nearly everywhere](https://gist.github.com/JoeyBurzynski/617fb6201335779f8424ad9528b72c41). Also add some basic image styling to blog posts, working in combination with `anti-image-reflow` to fit images to the blog width without causing jank. Customise CSS by editing `_includes/main.css`. |
| _Favicons_ | Generate icons for your site using [https://realfavicongenerator.net/](https://realfavicongenerator.net/), or disable favicons using `_config.yml` to use a low-byte-count alternative. Change file names or theme colours using `_config.yml`. |

#### Dev
_Build locally_
1. Clone this repository: `git clone https://github.com/Cutwell/featherweight.git`
2. Download the project dependencies: `bundle install`
3. Run a local Jekyll server: `bundle exec jekyll serve`

_Build .gem_
1. Update version in `.gemspec`
2. Build with `gem build featherweight.gemspec`
3. Push to RubyGem with `gem push featherweight-x.x.x.gem`

#### Credit
feather by GREY Perspective from <a href="https://thenounproject.com/browse/icons/term/feather/" target="_blank" title="feather Icons">Noun Project</a>