michaeljdeeb.com

GitHub Pages, Jekyll, and Mavericks, Oh My!

Invalid DateTime

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)

  1. Download Xcode from the Mac App Store
  2. Navigate to Xcode > Preferences > Downloads > Command Line Tools and click the download arrow. (You can also start the installation via Terminal with xcode-select --install in Mavericks.)

Install Brew

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 rvm command.

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 ruby --version.

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

  1. Pull your GitHub Pages project.

    • If you need to set one up check out the GitHub Pages site.

  2. In Terminal run: jekyll new /path/to/repository/project-name

    • Note: /path/to/repository/project-name must be a path, you cannot run jekyll new from 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.
  3. In Terminal change directory to your project: cd /path/to/repository/project-name

  4. Then in Terminal run: jekyll serve --watch --drafts

    • --watch updates your local copy every time you save a file.
    • --drafts shows 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 ctrl-c
  5. 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.
  6. 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.