Jekyll: installing a gem-based theme

Question

I've succeeded in creating my first static website with Jekyll v3.4.3. Now I would like to change the default "minima" theme to another gem-based theme like, for example, jekyll-theme-minimal

As far as I understood, according to the jekyll documentation this would just require the following steps:

1.- Add the theme to your site’s Gemfile:

gem "jekyll-theme-minimal", "~> 0.0.3"

2.- Install the theme:

bundle install

3.- Add the following to your site’s _config.yml to activate the theme (comment out "minima" and add the new one):

theme: jekyll-theme-minimal

4.- Build your site:

bundle exec jekyll serve

I followed these steps, but building the site (step 4) brings the following error:

$ bundle exec jekyll serve
Configuration file: /home/username/jekyll/myblog/_config.yml
Configuration file: /home/username/jekyll/myblog/_config.yml
            Source: /home/username/jekyll/myblog
       Destination: /home/username/jekyll/myblog/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
     Build Warning: Layout 'post' requested in _posts/2017-03-22-welcome-to-jekyll.markdown does not exist.
  Liquid Exception: Could not locate the included file 'icon-github.html' in any of ["/home/username/jekyll/myblog/_includes"]. Ensure it exists in one of those directories and, if it is a symlink, does not point outside your site source. in about.md

I see that the new gem-based theme has been installed

$ bundle show jekyll-theme-minimal
/home/username/.gem/ruby/2.4.0/gems/jekyll-theme-minimal-0.0.3

But I've noticed that the new theme has no _includes directory. Also, I see that the about.md file in my Jekyll site directory is still referencing the default "minima" theme:

$ cat ~/jekyll/myblog/about.md 
---
layout: page
title: About
permalink: /about/
---

This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/)

You can find the source code for the Jekyll new theme at:
{% include icon-github.html username="jekyll" %} /
[minima](https://github.com/jekyll/minima)

You can find the source code for Jekyll at
{% include icon-github.html username="jekyll" %} /
[jekyll](https://github.com/jekyll/jekyll)

How can I change in my site the default "minima" theme to another gem-based theme?

Answer 1

Jekyll themes documentation specifies a general procedure to use a new theme, but as Jekyll is very flexible, it can't guarantee that every theme will work out of the box.

Jekyll default installation, comes with example data, pages layout and includes.

Minimal theme has a default layout and no includes, as the example posts that comes with Jekyll uses includes and use the page layout, it won't work.

After installing the minimal theme, you need to make sure all your posts have layout: default as their layout (no layout: pages or any other one), and posts content does not has includes.

In this case, after tweaking about.md like that, it would look like this:

---
layout: default
title: About
permalink: /about/
---

This is the base Jekyll theme. You can find out more info about customizing your Jekyll theme, as well as basic Jekyll usage documentation at [jekyllrb.com](https://jekyllrb.com/)

You can find the source code for the Jekyll new theme at:
[minima](https://github.com/jekyll/minima)

You can find the source code for Jekyll at
[jekyll](https://github.com/jekyll/jekyll)

Or if you don't want to change the content of the posts, just provide the missing includes and/or layouts creating these folders and creating the proper missing files that you would like to have using the new theme, you are not restricted to just use what the theme uses Overriding theme default