Search code examples
jekyllgithub-pagesjekyll-theme

How do I install one of Github Pages' Jekyll themes for local preview?

I'm trying to install Github Pages' Slate theme on my CentOS 7 VM so I can locally preview my new site using the bundle exec jekyll serve command.

I followed the instructions as best as I could.

  • I changed the theme minima to jekyll-theme-slate in my _config.yml file.
  • Then I changed gem "minima", "~> 2.0" to gem "github-pages", group: :jekyll_plugins in my Gemfile file.

After that (since these are their only instructions), I ran bundle exec jekyll serve and it told me I had gems that weren't installed (duh), and suggested running bundle install.

  • I ran bundle install, which told me there was a conflict in version types of the dependencies and it suggested that bundle update could potentially resolve that issue.
  • No problem, I ran bundle update. A few plugins/features actually reverted versions here, but I got the Slate theme installed on my machine now, version 0.0.4 for whatever reason.

After that, I ran bundle exec jekyll serve again. I got this error:

Configuration file: /home/peri/my-site/_config.yml
Configuration file: /home/peri/my-site/_config.yml
jekyll 3.4.3 | Error:  Could not find a JavaScript runtime. See https://github.com/rails/execjs for a list of available runtimes.

In a way, that error makes sense. For a custom theme to work, I probably need a tool to run their custom scripts. But first, I noticed this extra section in the theme's installation instructions, which directly mentions being able to locally preview the site with that theme.

  • I downloaded the source, instead of cloning it...I don't need the .git stuff do I?
  • I edited the script/bootstrap file because /usr/local requires root and using sudo doesn't know about any binary called gem or bundle. I changed gem and bundle to their respective absolute paths and ran sudo ./script/bootstrap inside of slate-master.

Point of the story is, it didn't work for my home/peri/my-site directory when I ran bundle exec jekyll serve. Presumably, it's because they intended for the user's site to be integrated into their theme's source code? That doesn't seem intuitive or correct. So, I investigated ExecJS.

  • I installed it. gem install execjs
  • I added gem "execjs", "2.7.0" to my Gemfile file.

Got the same error as before.

How am I supposed to install this Jekyll theme?

Solution

  • Follow these steps after changing the theme in _config.yml:

    1. Gemfile should have only this content:

      source "https://rubygems.org"
gem "github-pages"

    2. remove bundler current config: rm -r .bundle/

    3. remove Gemfile.lock: rm Gemfile.lock

    4. Install local dependencies in an isolated folder just for this website: bundle install --path=vendor/bundle

    5. You won't have post and page and home themes, you will need to use just default in all your posts.

    6. Generate and run server: bundle exec jekyll s