featherweight
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
- Clone this repository:
git clone https://github.com/Cutwell/featherweight.git - Download the project dependencies:
bundle install - Run a local Jekyll server:
bundle exec jekyll serve
Build .gem
- Update version in
.gemspec - Build with
gem build featherweight.gemspec - Push to RubyGem with
gem push featherweight-x.x.x.gem
Credit
feather by GREY Perspective from Noun Project