Getting Started

If you want, you can just use the official Jekyll install docs for the first part of this guide; this provides a way to separate your Jekyll project from any already installed Ruby environment, or any other Ruby projects. I’ve had trouble in the past with managing Ruby; this should provide a good basis for development going forward. If you’re all set, skip past the installation parts.

These instructions are for Mac. Linux should be similar, except for the Homebrew (brew) parts; instructions for compiling are on the respective project homepages. I don’t know how to do this on Windows; it might be totally different. I think you need something like RubyInstaller, and then you can move on to the “install Jekyll” part later on.

So, without further ado, let’s get started. We’re going to use the latest hipster stuff; things have actually progressed nicely since a few years ago.

Note that last command used Ruby to install Homebrew; it’s a Ruby app, and uses the OSX standard system Ruby. That’s the last time we need to use the System Ruby; OSX currently is only v2.0, and Jekyll requires v2.1.

Building a Ruby environment

We are supposed to put some stuff in ~/.bashrc or /etc/profile; I tend to put my config details in ~/.profile, because it’s kinda the Mac way, I always have in the past, and I get confused easily. YMMV. Seems to work.

Let’s put in a simple config file, which Chruby uses to switch versions automatically, depending on which directory we’re in.

echo '2.4.1' > .ruby-version
cat .ruby-version

That was enough for Chruby to switch to a different version of Ruby. If we switch temporarily to the parent directory and back, we’ll see the Ruby gets changed back to the system Ruby, and then back again to our current Ruby, without any fuss. Slick.

Extra credit: if you want to keep your Gems (i.e. libraries/modules) discrete and tidy as well, you might want to check out Gem Home, which keeps Ruby Gems in a local directory, instead of installing them globally. This is useful if you’re doing a lot of Ruby work, but it’s overkill for our purposes.

Installing Jekyll

Now that we have a discreet Ruby, we can install Jekyll. At this point, I’m leaning on the official install docs. This uses the Ruby package manager, RubyGems, to install Jekyll.
gem install jekyll
$ jekyll –version
jekyll 3.4.3

Let’s initialize our project with a Git repository, and do a first commit, just to make sure everything is wired up correctly.

$ git init .
$ git add -A
$ git commit -m "First commit."

We’ll need Bundler, which Jekyll uses to install stuff.

$ gem install bundler

Create a new Jekyll project in our current directory, and serve it via HTTP.

$ jekyll new .
$ jekyll serve

Now, if you visit http://127.0.0.1:4000/ in a web browser, you can see a “Hello World” kind of site. Lets keep this running for a while; you could press Ctrl-C to kill the process, but instead just open a new terminal tab/window. This will let you work on your site while Jekyll continues to serve it in the background.

You can find a file called “welcome-to-jekyll” (or something) in the _posts directory. Open it up in your text editor, and change some text. When you reload your browser, you’ll find that Jekyll has updated the page for you, without having to restart the server. You’ll also find a _config.yml file; take a moment to edit the Title, Description, Email fields; changing the site configuration will require you to restart the server, however.

Putting our Jekyll site on GitHub Pages

Next, we’ll get our Jekyll site up on GitHub. We’ll rely heavily on GitHub’s own documentation on the subject: worthwhile to peruse.