Using Jekyll within GitHub Pages is relatively straight forward, but due to some operating system (OS 10.9.2, Xcode 5.1) issues it became more difficult than necessary.
At the time of writing, if you are using OS X, do not use the version of ruby that comes with your computer.
Issue #2125 is the problem and although the ARCHFLAGS work around worked to install Jekyll, it didn’t work when running
jekyll serve --watch.
Install Xcode (Command Line Tools)
- Download Xcode from the Mac App Store
- Navigate to Xcode > Preferences > Downloads > Command Line Tools and click the download arrow.
(You can also start the installation via Terminal with
xcode-select --installin Mavericks.)
Navigate to brew.sh for more information or type:
ruby -e "$(curl -fsSL https://raw.github.com/Homebrew/homebrew/go/install)"
Install RVM & Ruby
Navigate to rvm.io for more information or type:
\curl -sSL https://get.rvm.io | bash -s stable
At this point I had to quit Terminal and reopen it to get it to recognize the
After reopening Terminal you’ll want to run
rvm install 2.1.1 or you can attempt to find a newer version of Ruby by running
rvm list known.
The install should’ve switched to this version of Ruby (2.1.1), but to make sure you aren’t using the native version of Ruby, type
rvm use 2.1.1 or verify you’re using the latest by typing
which ruby and
Finally, Install Jekyll
Navigate to jekyllrb.com for more information or type:
gem install -V jekyll
You can omit the
-V, but your Terminal window will be blank for a lengthy amount of time.
Configure your GitHub Pages Project
Pull your GitHub Pages project.
- If you need to set one up check out the GitHub Pages site.
In Terminal run:
jekyll new /path/to/repository/project-name
/path/to/repository/project-namemust be a path, you cannot run
jekyll newfrom within the directory you wish to use.
- If Jekyll says
Conflict: /path/to/repository/project-name exists and is not empty., you’ll have to move the files in your project to a temporary location and rerun the command.
- In Terminal change directory to your project:
Then in Terminal run:
jekyll serve --watch --drafts
--watchupdates your local copy every time you save a file.
--draftsshows drafts on your local copy
- Note: on OS X with the native version of Ruby this is where things fell apart and really stopped working.
- Note: to stop hosting a local copy you can press
- At this point if another service isn’t using port 4000, you can navigate to http://localhost:4000/ or http://0.0.0.0:4000 after a couple minutes have passed.
- Jekyll’s documentation has great information about the Folder Structure and you’ll probably want to reference their documentation from here on out.
Good luck and hopefully this guide was of some help!
Also, feel free to checkout the source of this website.