Minimal-mistakes: error: cannot load such file -- jekyll-include-cache

[cseas]

Environment

• Jekyll version: 3.8.5
• Operating system: Ubuntu 18.04.1

Problem

I followed the installation procedure by downloading the files but on running bundle exec jekyll serve, it kept giving me this error:

Dependency Error: Yikes! It looks like you don't have jekyll-include-cache or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- jekyll-include-cache' If you run into trouble, you can find helpful resources at https://jekyllrb.com/help/! 
jekyll 3.8.5 | Error:  jekyll-include-cache

[cseas]

I wasn't able to run the site locally till I made the change in the pull request #1938 after which it ran fine.

[mmistakes]

Shouldn't need that gem. Its marked as a dependency with the theme gem. It's needed when using the GitHub Pages gem though since they don't enable it by default.

[mmistakes]

Adding jekyll-include-cache to the plugins array in_config.yml is all that's needed.

See the /test for for a working example.

[cseas]

I deleted the gemspec file before running the site.

The Quickstart guide instructs to delete the gemspec file after cloning the repo. Perhaps that's why the problem occurred?

In that case, the gemspec shouldn't be instructed to be removed in the Quickstart. This can get confusing for beginners trying to use the theme.

[mmistakes]

No that's correct, you should delete the .gemspec. I only linked to it to show that the theme gem declares jekyll-include-cache as a dependency. You don't need to install the gem in your Gemfile. If you have the MM gem it will install jekyll-include-cache.

plugins:
  - jekyll-include-cache

What you do need is to have it listed in your plugins: array in _config.yml. That's what the error is all about.

[ashmaroli]

You don't need to install the gem in your Gemfile.. The MM gem will install jekyll-include-cache..
..need is to have it listed in your plugins: array in _config.yml. That's what the error is all about.

@mmistakes This is a misunderstanding.
The error is actually from Jekyll complaining about "not being able to load the requested plugin".
(For the uninitiated, this happens because bundle exec .. loads only those gems (and their dependencies) listed in the Gemfile or the Gemfile.lock.)

Like you mentioned above, under normal conditions, one does not need to list the plugin in their Gemfile since it will be automatically loaded by Jekyll.
But when using the remote_theme configuration, customers are no longer using the "theme-gem" (and therefore neither the theme-gem's gemspec) per se. The remote-theme plugin links to the GitHub repo and only loads the themes layouts & other templates, ignoring dependencies entirely.

 

@cseas The above means that the you will simply have to un-comment the concerned plugin(s) in the recommended Gemfile (the same Gemfile in your PR) to resolve this issue.

[mmistakes]

@ashmaroli The fact that GitHub Pages supports but doesn't enable the jekyll-include-cache plugin has been a real thorn in my side. Kind of wish I never added the feature to the theme.

The casual Jekyll user (who is likely most of GitHub Pages users) doesn't really understand the nuisances of how Jekyll works, reads its documentation, or care what a remote theme versus a Ruby gem theme are.

[ashmaroli]

The fact that GitHub Pages supports but doesn't enable the jekyll-include-cache plugin has been a real thorn in my side.

I empathize with you for having to shoulder this responsibility.

The reason this plugin is not enabled by default is because the casual user would not be able to fully realize the risks from the plugin's gotcha.

If it helps reduce the pain, I think all this needs is a Comment in the Gemfile and a note in the installation docs asking the user to first understand the plugin's effects and then list the plugin in both Gemfile & the config file if they want to optimize their includes.

[cseas]

Yes, maybe a little hint about the difference between the gem and remote theme configuration should be better explained for beginners. I've successfully deployed the theme now but it took me a while to figure out how to setup the theme with GitHub Pages properly.

Using the theme's gem causes GitHub Pages to send warning emails everytime you push a commit, saying this isn't a supported theme.

And removing the theme gem causes all the plugin related errors when trying to run jekyll locally. Instructions weren't really clear about how to set this up with GitHub Pages and locally without facing gem and plugin related errors that a beginner might really have no clue about.

[stefanbschneider]

So what was the solution? Just adding to the plugins array in _config.yml didn't solve the problem for me.

[ashmaroli]

The solution is:

• Either uncomment # gem 'jekyll-include-cache' if there's such a line in your Gemfile or
• Add gem 'jekyll-include-cache' in the Gemfile and
• Add jekyll-include-cache to the plugins: key in your _config.yml

[hotwebmatter]

This actually helped me to resolve a similar issue with a different plugin. Thanks for the explanation!

[toolson12]

The solution is:

• Either uncomment # gem 'jekyll-include-cache' if there's such a line in your Gemfile or
• Add gem 'jekyll-include-cache' in the Gemfile and
• Add jekyll-include-cache to the plugins: key in your _config.yml

Thank you for the detailed explanation. This also solved my issue when I was trying to use Minimal Mistakes in Netlify.

The official docs indicates that you have to create a new Gemfile with two lines of code (source "https://rubygems.org" and gem 'github-pages') but I was not including gem 'jekyll-include-cache' line. That made the trick!

Gemfile

source "https://rubygems.org"
gem 'github-pages'
gem 'jekyll-include-cache'