Adding a favicon to a Jekyll-based static website

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.

when using

$ jekyll serve --watch --livereload

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, errors¹. 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 it just “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 multiple “favicons”.

So, how to create these icons? As recommended in issue 949 of the Minimal Mistakes GitHub repo one can use a favicon generator service such as RealFaviconGenerator.

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.

The Jekyll documentation recommends using an assets folder for static files such as images. Also, the Minimal Mistakes author recommends using /assets/images 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 like this:

<!-- start custom head snippets -->

<!-- insert favicons. use https://realfavicongenerator.net/ -->

<link rel="apple-touch-icon" sizes="180x180" href="/assets/images/apple-touch-icon.png">
<link rel="icon" type="image/png" sizes="32x32" href="/assets/images/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="16x16" href="/assets/images/favicon-16x16.png">
<link rel="manifest" href="/assets/images/site.webmanifest">
<link rel="shortcut icon" href="/assets/images/favicon.ico">
<meta name="msapplication-TileColor" content="#da532c">
<meta name="msapplication-config" content="/assets/images/browserconfig.xml">
<meta name="theme-color" content="#ffffff">

<!-- end custom head snippets -->

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.

Wrapping up

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!

Is there anything that I’ve missed? Was this post helpful? How could I make it better? Let me know in the comments section or simply drop me a line via email or ping me on Mastodon.

---

Update (2022-04-01)

A reader pointed out to me that RealFaviconGenerator is only able to process images up to 2MB in size. They mentioned this favicon generator on websiteplanet.com as an alternative because it can process files up to 5MB in size. I’ve not used this new service and hence can’t endorse it, however it might be of use to anyone who needs to process larger images in order to generate their favicons.

1. Thank you, Captain Obvious! ↩

Support

If you liked this post and want to see more like this, please buy me a coffee!