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

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.

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).

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 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:

theme: featherweight

Also create a Gemfile file in the repository root, with the following content:

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 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.

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.
gzip compression	Files are compressed using 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 algorithm. We serve .gz and .html as fallback, although .br has good support.
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. 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/, 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 Noun Project