How to build a Jekyll + GitHub Pages site
This site is built using Jekyll that turns the Markdown and HTML templates into a themed static site. To run Jekyll, install the Ruby via the Ruby Version Manager and install the github-pages
Gem (a Ruby package) via Bundler. Installing the github-pages
Gem will install the Jekyll executable.
Step 1: install Ruby with the Ruby Version Manager (RVM):
There are too many ways to install Ruby. If you (like me) don’t know anything about Ruby then just install Ruby with RVM.
- Following the instructions at https://rvm.io to install RVM. (Follow the Basic Install instructions to install the latest stable version of RVM)
- For Ubuntu users, read this after you read the above: https://github.com/rvm/ubuntu_rvm
Make sure you install the version of ruby
(via rvm install
) compatible with GitHub Pages. Set the current
(and default
) ruby
installation to the compatible version via rvm alias create default <version>
.
Step 2: install dependencies, build and serve the site
Follow the github.com instructions.
tl;dr:
bundler
should be installed as part ofruby
2.x.- You basically only need the
github-pages
gem, and can specify the dependency as part of theGemfile
bundle install
to install dependenciesbundle exec jekyll serve
to build and serve the site locally tolocalhost:4000
Troubleshooting:
- Add:
[[ -s "$HOME/.rvm/scripts/rvm" ]] && source "$HOME/.rvm/scripts/rvm"
to your.bashrc
or.zshrc
etc. ifruby
is not found. - Check
github-pages
gem compatibility at https://pages.github.com/versions/- As of Apr 2022, Jekyll 3.9 requires Ruby 2.7.3, and is not compatible with Ruby 3.x