Install Jekyll on Funtoo
I am installing Jekyll locally on my funtoo instance, for development of a github.io site.
I begin by installing the required system packages:
kenneth@kennethd:/tmp/jekyll-test$ sudo emerge dev-lang/ruby
kenneth@kennethd:/tmp/jekyll-test$ sudo emerge net-libs/nodejs
Next, I create a ~/.gemrc
, my main purpose is to enable the --user-install
flag by default.
It absolutely mystifies me that the ruby community is ok with the way packages are installed system-wide by default.
Other configuration options are documented here
benchmark: false
verbose: true
# Enable/disable automatic updating of repository metadata
update_sources: true
# Print backtrace when RubyGems encounters an error
backtrace: true
# do not generate local documentation for every installed gem
# install packages into my $HOME
# rewrite gems to use `/usr/bin/env ruby` if not already using env shebang
# suggest alternates when gems are not found
gem: --no-ri --no-rdoc --no-document --suggestions --user-install --env-shebang
When installing gems to your $HOME, you have to add the directory they are
installed into to your $PATH. For bash, add something like this to ~/.bashrc
and then source the file in your terminal (. ~/.bashrc
):
if [[ ":$PATH:" != *":$HOME/.gem/ruby/2.2.0/bin:"* ]] && [[ -d "$HOME/.gem/ruby/2.2.0/bin" ]]
then
export PATH="$PATH:$HOME/.gem/ruby/2.2.0/bin"
fi
Install some gems:
kenneth@kennethd:/tmp/jekyll-test$ gem install jekyll
kenneth@kennethd:/tmp/jekyll-test$ gem install jekyll-docs
kenneth@kennethd:/tmp/jekyll-test$ gem install pygments.rb
kenneth@kennethd:/tmp/jekyll-test$ gem install bundler
Create a new site:
kenneth@kennethd:/tmp/jekyll-test$ jekyll new .
kenneth@kennethd:/tmp/jekyll-test$ ls -l
total 24
-rw-r--r-- 1 kenneth kenneth 810 Oct 21 17:55 Gemfile
-rw-r--r-- 1 kenneth kenneth 3542 Oct 21 17:59 Gemfile.lock
-rw-r--r-- 1 kenneth kenneth 1408 Oct 21 17:53 _config.yml
drwxr-xr-x 2 kenneth kenneth 4096 Oct 21 18:51 _posts
-rw-r--r-- 1 kenneth kenneth 524 Oct 21 17:53 about.md
-rw-r--r-- 1 kenneth kenneth 213 Oct 21 17:53 index.md
You will want to edit the auto-generated _config.yml
to add your own name,
etc. If you noticed, I had also installed the pygments.rb
gem above, to use
it on my site I have to add a line to _config.yml
(but see
below before following along):
highlighter: pygments
And then to allow the site to build with that reference in place, add to the
Gemfile
:
gem "pygments.rb", "~> 0.6"
The ~> 0.6
version specifier means: upgrade to most recent sub-version of
0.6, but don’t automatically upgrade to 0.7 or above. I chose it because I
already have two versions of pygments.rb on my system (probably due to
dependencies):
kenneth@kennethd:/tmp/jekyll-test$ gem list --local | grep pygments
pygments.rb (0.6.3, 0.6.1)
At this point we should be able to launch a server and navigate to http://127.0.0.1:4000/
kenneth@kennethd:/tmp/jekyll-test$ bundle install
kenneth@kennethd:/tmp/jekyll-test$ bundle exec jekyll serve
Configuration file: /tmp/jekyll-test/_config.yml
Configuration file: /tmp/jekyll-test/_config.yml
Source: /tmp/jekyll-test
Destination: /tmp/jekyll-test/_site
Incremental build: disabled. Enable with --incremental
Generating...
done in 0.286 seconds.
Auto-regeneration: enabled for '/tmp/jekyll-test'
Configuration file: /tmp/jekyll-test/_config.yml
Server address: http://127.0.0.1:4000/
Server running... press ctrl-c to stop.
Ok! Let’s make the first commit:
kenneth@kennethd:/tmp/jekyll-test$ git init
kenneth@kennethd:/tmp/jekyll-test$ git config user.name "Kenneth Dombrowski"
kenneth@kennethd:/tmp/jekyll-test$ git config user.email kenneth@ylayali.net
kenneth@kennethd:/tmp/jekyll-test$ git remote add origin git@github.com:kennethd/kennethd.github.io.git
kenneth@kennethd:/tmp/jekyll-test$ git add .gitignore Gemfile _config.yml _posts/ about.md assets/ index.md
kenneth@kennethd:/tmp/jekyll-test$ git commit -m "install jekyll"
kenneth@kennethd:/tmp/jekyll-test$ git push origin master
First problems
All of this worked perfectly on my funtoo instance, but as I pushed to github.io, a few problems cropped up:
First, the Gemfile
contained some unsupported lines, for github-pages
, I
reduced it to the following:
source "https://rubygems.org"
gem "minima", "~> 2.0"
gem "github-pages", group: :jekyll_plugins
Second, pygments
is not supported by github.io, you have to use rouge
. In
the end, my _config.yml
looked something like this:
title: kennethd.github.io
email: kenneth@ylayali.net
author: Kenneth Dombrowski
description: >
Notes about Linux, Programming, Web Development, and Data Sciences
baseurl: ""
url: "https://kennethd.github.io"
twitter_username: kennnethd
github_username: kennethd
markdown: kramdown
theme: minima
highlighter: rouge
gems:
- jekyll-feed
exclude:
- Gemfile
- Gemfile.lock
Third, the files required by use of the minima
theme were not discovered in
the github.io environment. In the end I just copied all of the files from the
theme into my project’s _layouts
, _includes
, and _sass
directories,
which is an entirely unsatisfactory solution, and something I will have to
revisit.