In the post I will be using the acronym MM and the full name Minimal Mistakes interchangeably.
Introduction on themes
Jekyll has a built-in support for themes that allows you to use templates created by the community.
The theme system is designed so themes are packaged into Ruby gems but assets and layouts can easily be overridden to customize the site’s content.
For sites hosted on GitHub Pages, there is also the possibility to consume the theme directly from a GitHub repository.
The Jekyll documentation has an article that explains how the theme system works.
Installing the theme
Because it supports the remote theme setup, installing the Minimal Mistakes theme is pretty easy.
You simply modify the
_config.yml file so that it contains the following entry and you any other theme-related entry.
A more detailed guide on how to install the Minimal Mistake theme can be found on the site of the theme itself.
Additionally, you can use the
minimal_mistakes_skin property to select which of the many skins available you prefer for your site.
Finally, as explained by Matthias Lischka in his blog, it’s a best practice to fork the repository and have the
remote_theme directive pointing to your own fork of the repository.
This is the directive in my
Customizing the site
Once the theme is installed, it’s time to customize the site to make it ours.
Following Jekyll’s best practices, Minimal Mistakes puts a lot of emphasis on the Liquid templates and data provided by the
_config.yml, the data files and the Front Matter of each page.
Let’s start with something easy: the footer.
The footer presents some links that can help visitors contacting you.
This is my footer as of the time of writing this article:
You can see that my footer shows five links: GitHub, LinkedIn, Twitter, Stack Overflow and the RSS feed.
These links are created programmatically at build time and are based on a data structure placed in the
Here is the snippet that is used to render the footer of the website.
footer: links: - label: "GitHub" icon: "fab fa-fw fa-github" url: "https://github.com/Kralizek" - label: "LinkedIn" icon: "fab fa-linkedin" url: "https://www.linkedin.com/in/renatogolia/" - label: "Twitter" icon: "fab fa-fw fa-twitter-square" url: "https://twitter.com/Kralizek" - label: "Stack Overflow" icon: "fab fa-fw fa-stack-overflow" url: "https://stackoverflow.com/users/82540"
Each item is represented by a name, a FontAwesome icon and a link.
The Minimal Mistakes theme has an area where you can tell your visitors a little about yourself.
Like the footer, this area can be customized in the
Here is the snippet that is used to render the author area of the website.
author: name : "Renato Golia" avatar : "/assets/images/rg.jpg" bio : >- My name is Renato. I was born in Naples, Italy but I've been living in Stockholm, Sweden since 2008. I love working with .NET and AWS and to combine the two together. You can read more about me in the [About me](/about/) section. location: "Stockholm, Sweden" twitter: "Kralizek" linkedin: "renatogolia" github: "Kralizek" stackoverflow: "82540" links: - label: "Email" icon: "fas fa-fw fa-envelope-square" url: "mailto:firstname.lastname@example.org" - label: "Resume" icon: "far fa-fw fa-file-pdf" url: "/assets/files/resume-renato-golia.pdf"
As you can see, the theme natively supports some social media sites like Twitter, LinkedIn, GitHub, Stack Overflow. Here you can see all the social media that are natively supported.
For all others, you can use the
The theme also supports the possibility to display a different author for each post. This is very convenient if your blog welcomes external authors. Here you can see how to support multiple authors.
Top bar menu
Until now, we’ve been modifying the
_config.yml file to customize how the site looks and which information is displayed.
The configuration of the top bar, also known as Masthead in MM’s lingo, lies in the
navigation.yml data file that you can find in the
In the screenshot above, I highlighted two areas.
The one on the left simply displays the content of the
site.title setting that can be customized in the
The area on the right, instead, renders the structure available in the
To be more precise: the variable
main found in the
navigation.yml file in the
Here is the relevant excerpt of the file.
main: - title: "About me" url: /about/ - title: "Posts" url: /years/ - title: "Pages" url: /pages/ - title: "Tags" url: /tags/
Like in most responsive websites, the Masthead section moves items into a toggle menu when there is not enough space to display all elements.
You can peek at the file responsible for rendering the Masthead to see how it’s implemented.
The website of Minimal Mistakes has a simple animation that explains this feature.
Once we’ve modified the basics of the look and feel of the site, it’s time to focus on some less obvious details.
Favicons initially were the icons displayed by browsers in the address bar. Over time, with the growing popularity of PWA and similar technologies, favicons are used when the website is pinned on the desktop, on the home screen of a mobile device and so on.
For this reason, it’s important to have a proper support for it.
Unfortunately, the beauty of standards is that there are many, so each device/operative system/platform has their own standard to follow.
Anyway, the bare minimum is to have a
favicon.ico file in the root of your website. This file will be requested from the browsers regardless if the HTML page has an explicit link to any icon.
Once you have you have your icon file, you can use RealFavIconGenerator to generate all the other files you need.
You can also use it to check if your site is set up correctly. Here is a report for this site.
Personally, I’ve placed all files with the exception of
favicon.ico in the directory
/assets/images/favicons/. This approach allows me to keep the root of the site (and therefore of the repository) quite clean.
Now that the files are in place, we need to modify the website so that it includes the proper HTML to link to them.
To do so, simply create a file with this path
/_includes/head/custom.html and paste the following content (actually the one suggested by RealFavIconGenerator).
<link rel="apple-touch-icon" sizes="180x180" href="/assets/images/favicons/apple-touch-icon.png"> <link rel="icon" type="image/png" sizes="32x32" href="/assets/images/favicons/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="/assets/images/favicons/favicon-16x16.png"> <link rel="manifest" href="/assets/images/favicons/site.webmanifest"> <link rel="mask-icon" href="/assets/images/favicons/safari-pinned-tab.svg" color="#5bbad5"> <link rel="shortcut icon" href="/favicon.ico"> <meta name="msapplication-TileColor" content="#e5e5e5"> <meta name="msapplication-config" content="/assets/images/favicons/browserconfig.xml"> <meta name="theme-color" content="#ffffff">
If you are wondering how this could solve the issue, Jekyll gives priority to local files over files found in the repository pointed to by our
remote_theme setting. This is the file we are overriding.
HTTP cache busting
If you find yourself working a lot with the CSS of the site, you might find annoying the long caching set for static assets.
To circumvent the caching, we can instruct Jekyll to create a new URL for the main CSS file every time we rebuild the site. This is something you should disable when you have finished tinkering with the CSS.
We will be using the same process used for the favicon links: we are going to create a new file that will override the file found in the repository.
Unlike for the favicon links, the modification we are going to introduce was not planned by the author of Minimal Mistakes.
First thing first, let’s create a file whose path will be
_includes/head.html and let’s copy the content of the original file.
Then, let’s replace the line where the
main.css file is linked with the following one:
<link rel="stylesheet" href="/assets/css/main.css?v=1606649760">
The section we have added,
v=1606649760, simply adds a querystring token based on the time of build.
Every time we build the site, that token will be recalculated, giving us the possibility to skip caching layers and access the fresh CSS file as soon as possible.
Minimal Mistakes has the support for tracking providers like Google Analytics built-in.
To enable this, simply go into the
_config.yml and add the following snippet:
analytics: provider: "google" google: tracking_id: "your-ga-tracking-id" anonymize_ip: true
Adding this snippet will cause Jekyll to render the needed code to include the Google Analytics snippet.
The theme also supports other providers or, if your provider of choice is not supported, a custom HTML snippet.
In this post we’ve seen how Jekyll supports themes and how they can be installed.
Then we have customized it so that it matches our needs and tastes.
This is the last post of this series but more posts will come about Jekyll in the future.