Having a favicon on your website can be a nice touch, especially if you’ve got a cool logo. Unfortunately, I don’t have a cool logo, however I thought I’d add a favicon to my site anyway. Here’s a detailed description of how to add a favicon to a Jekyll-based static website.
It’s not a bug, it’s a feature
But first, what just what is a favicon? As the Wikipedia article about favicon mentions, the word is short for favourite icon and the favicon file is typically used by web browsers to display the favicon in the address bar for a given page or in the page’s tab (for browsers supporting tabbed pages).
The only reason I realised such a thing existed was due to my browser complaining that the file didn’t exist when I was developing a web application or building the static files for this blog. For instance, I’d get errors like this
[2020-08-11 09:56:55] ERROR `/favicon.ico' not found.
and when the browser reloaded the page I was editing.
Now, I’m not a fan of error messages, because they usually point to, well, errors1. And errors mean that something is wrong. In this case, there wasn’t really anything wrong, it was just that the browser was letting me know that something it expected to be there wasn’t, and it turns out that the absence of this file isn’t a show-stopper. Nevertheless, I feel that such messages are broken windows that should be repaired, otherwise one gets used to things being “a bit broken” and then, over time, the broken things accumulate until the chaos is overwhelming.
The question then becomes: how to stomp on this bug (if one can call it that)?
Not Jekyll’s problem
I use the Minimal Mistakes Jekyll theme for this site and found that the issue has been raised several times in that project. Digging a bit further I found that the Minimal Mistakes author has answered people asking about the issue multiple times both in issues in his theme’s GitHub repository as well as in more general Jekyll forums (kudos to him for his persistence and patience with users repeatedly asking the same question). As he quite rightly mentions, this isn’t a Minimal Mistakes or Jekyll issue, it’s more of a web development issue and hence isn’t something that Jekyll or Jekyll themes need to implement directly.
Stop raving, start fav-ing
For the remainder of this discussion I’m going to follow the advice outlined in issue 949 of the Minimal Mistakes GitHub repo.
Create the favicons
What? Favicons? Isn’t a favicon? I.e. singular? Well, yes, as it turns
out, there are now many favicons. Once upon a time it was only necessary to
include the file
favicon.ico in the root directory of your site, however
now different browsers and different platforms have multiple ways of
displaying what ends up being basically the same thing. To be fair, a
favicon can also be the icon used for your web app, hence there’s a need to
support not only desktop browsers but also browser-based apps on, for
instance, mobile platforms. This variety has lead to the need to have
Let’s give that a go. Navigate to https://realfavicongenerator.net/; you should see a page similar to that shown below.
This page gives you the opportunity to check the favicon status of your website; this is handy because it gives you an overview of the current situation before you start changing parts of your site.
Once you know the current status, it’s time to upload your favicon. For this step I’m going to assume that you already have an appropriate logo or photo as a PNG or SVG that you would like to use as your favicon. Take note of the tip below the “Select your Favicon image” button that your image should have equal height and width, and be at least 260x260 pixels for optimal results. I mean, if you’re going to go through the effort of creating a favicon, you might as well use an image with sufficient resolution so as to get a good end result. In my case I chose the photo I use for my blog’s bio section, which makes sense for a personal blog, however if you’re doing this for a company, or if you have your own logo, you’ll probably want to use a logo rather than a photo.
To upload your favicon, click on the “Select your Favicon image” button. You should see a dialog asking you to select the image file of your photo or logo. Once the file has been selected and uploaded, RealFaviconGenerator will show you preview results of what your favicon will look like in various situations, such as on desktop browsers as well as how it would look as an icon on mobile operating systems.
Have a look at the preview output to satisfy yourself that the results are what you would like to have. If not, there are several extra parameters that you can play with to achieve the desired effect for your favicon.
Now, because I chose a photo as the basis of my favicon, the result for macOS Safari is less than awesome as you can see below.
Consequently I chose not to include an icon in this case and hence selected the “No icon” radiobutton. The pinned tab and Touch Bar output will use the first letter of my domain name to create a default icon, and I think this is ok for my use case. Of course YMMV.
If you scroll to the end of the page, you will find the “Favicon Generator
Options” section. Most of the default options are ok here, however because
image files are located in
/assets/images on my site (and I don’t want
lots of random files polluting the root directory of my website) I chose to
specify where the favicon files will be located, hence I specified
/assets/images in the text field within the “I cannot or do not want to
place favicon files at the root of my web site” option.
recommends using an
assets folder for static files such as images. Also,
the Minimal Mistakes author recommends using
as the path for favicons which is the convention I followed for my site,
hence this setting seems to be an appropriate alternative to the default
option that RealFaviconGenerator recommends.
Now click on the “Generate your Favicons and HTML code” button to generate a
package file (actually a zip
archive) of the favicon
files you need to add to your website. You are also presented with the HTML
that you need to add to the
<head> section of your site.
You now have everything you need to install the favicon on your site.
Install the favicons for Jekyll Minimal Mistakes
As shown in the image above, the first step is to download your package.
This will download a
.zip archive of the files you need. Once the file
has downloaded, you can unpack it into the
assets/images directory of
your Jekyll site:
$ cd assets/images $ unzip /path/to/favicon_package_v0.16.zip
The third step–copying the HTML code into the
<head> section of your
pages–requires the creation of a custom header file so that Jekyll can
include this code into the
<head> section of all pages when it generates
your site. I discussed this process in detail in my post about enabling
cookie consent on a Jekyll Minimal Mistakes site,
nevertheless here’s the brief version:
# create a local _includes/head directory $ mkdir -p _includes/head # find the path to the theme's gem directory $ bundle info minimal-mistakes-jekyll # copy the theme's default head custom.html into the local project $ cp /path/to/gems/minimal-mistakes-jekyll-4.19.1/_includes/head/custom.html _includes/head
Note that if you already have a local
custom.html file for for your
<head> sections, you don’t need to go through this process.
Now that you have a local copy of the default Minimal Mistakes
_includes/head/custom.html you can copy the HTML code from
RealFaviconGenerator into it. Your
custom.html file should look something
Now you just need to build your Jekyll site
$ JEKYLL_ENV=production jekyll build
and push the changed files to your website (assuming that’s how you deploy to your site!).
Theoretically, your favicon has been installed on your website, but let’s make absolutely sure.
Checking the final result
As in the beginning we tested what the site’s current favicon status was, we can now check what it is after having added this feature. In my case, I entered my blog’s web address into the “Favicon checker” and clicked “Check Favicon”.
Below you can see the results of this check:
The results are green; that looks good! Yay!
If you’ve been following along with your own site, you’ll find that the entry for “Mac OS X El Capitan Safari” will be red and it will report that the mask icon is missing. This is actually the behaviour that I want (in this case) because I’d chosen to use a photo for my favicon rather than a “proper” logo.
And that’s it! You’ve now got a favicon on your site, you’ve stomped on an annoying error message, and your site’s that much nicer than it was before. Congratulations!