Explanation on themes

Help
1

Hi, just started learning the Jekyll setup today and went through the Step by step tutorial. I’m also quite new to Ruby.

Thus far it’s been smooth, but I can’t get my head around the themes ecosystem.
I’ll host my site with nginx on my own server, so I want a gem based theme, I suppose. When checking out the themes over at rubygems.org, most of the most popular ones are themes for GitHub pages.

What does this imply? Can I still use them, or do they require extra customization, as I won’t be using GitHub pages? The installation instructions for this theme, for example, gives me the impression that it will work out of the box for GitHub pages, but there’s no Gem to install explicitly? I even have to install some github-pages gem just to get it to work on my machine?

I’ve tried to install a bunch of the plugins but then it seems that the plugins doesn’t support the verison used by jekyll new <sitename>, as I get this error:

Bundler could not find compatible versions for gem "jekyll":
  In snapshot (Gemfile.lock):
    jekyll (= 4.1.1)

  In Gemfile:
    jekyll (~> 4.1.1)

    jekyll-theme-cayman (~> 0.1.1) was resolved to 0.1.1, which depends on
      jekyll (~> 3.5)

I would be grateful if anyone could explain the setup, or point me to any article.

2

First off I am not a fan of the theme’s so my understanding of them in minimal.

All a theme is is some css/sass and some layouts (and maybe includes though this one doesn’t seem to have any). That particular theme is super simple, if I were you and was going to host it my self I would just clone/download the repo itself to get the sass and layouts folders and would then put those into an existing or new jekyll site. That should be all you need really, and then you don’t have to mess around with installing the theme gem and wondering how that is going to work.

The last line of your error I think is saying you have jekyll 4 but the theme will only work with jekyll 3.5 which is what GH is on still I think.

3

Thanks for the input, clarifies a bit. So all themes that are marked as theme for GitHub pages, means that Jekyll is at a certain version, and something else?

I’ll end up copying the sass and layout stuff manually, for sure.

The setup with different themes (gem, remote), and when the most popular themes doesn’t even support the current version, is quite confusing, but now I understood the basics at least, thanks.

4

A minor correction to @rdyar’s answer above.
jekyll (~> 3.5) means all versions starting from v3.5.0 but before v4.0.0 is allowed.

GitHub Pages currently uses v3.9.0.

5

@modestotech Once you get comfortable with using theme bundled as gems, you can switch to using the jekyll-remote-theme plugin, which will let you overcome the constraints on Jekyll version with practical limits.

6

I don’t think you need the github-pages gem. It bundles a ton of themes and plugins which you mostly won’t need especially outside of Github Pages.

I suspect also github-pages only works with Jekyll 3, since GitHub is a way off from supporting Jekyll 4. So that is why i think you got a Jekyll version error.

I made a basic theme here and the gh-pages branch is a demo you can run locally and it is live on GH Pages.

If you add the config and Gemfile to your project and run bundle install, then you’ll use both local Jekyll in your project and remote theme gem to download and use a given theme on github at build time. Not the theme is not in the Gemfile.

The actual theme is on the master branch. You can change your config to point to another remote theme instead

If you prefer to not use the remote theme plugin, you can also add a theme to your Gemfile and then set it as your theme in your config. But that will NOT work on GitHub Pages because gems are frozen. With the special case of remote theme plugin letting you pick any theme on github outside the standard themes.

7

Thanks for the further explanations.
I’m now testing a quite basic theme that works hassle free as theme specified in Gemfile and as theme in config file. Works good thus far. The GitHub pages integration seems great, but it gives a bit stepper learning curve, with different versions, and different ways of using themes.

8

Ok good

Here is the list https://pages.github.com/versions/

The locked gems in GH Pages is limiting on gems and not being able to run custom Ruby plugins, but once you lock your Gemfile list of gems to matched the list published on GitHub docs and you use remote theme plugin, there aren’t more surprises to learn.

The aim of the locked gems for the ones that are there on GH already reduces the barrier to setting up a site on GH Pages. You just need a README as homepage and a config and you’ve got a site running on GH Pages using Jekyll 3.9 and a choice of themes to set in the config e.g. theme: minima. No Gemfile needed. Unless you want local development or some other remote build flow.