I’ve been talking back and forth with @jasongreen on Twitter recently about Jekyll and hosting sites through GitHub as well as how to generate those files. Thought this would be a good opportunity to throw up a tutorial on getting started which we can build on with other aspects of the workflow (like pulling into your Reclaim space, generating Jekyll files locally, etc).
For this tutorial I’m going to walk through the process of hosting a barebones demo site with the Pixyll Jekyll theme. This theme is available on Github so it’s quite easy to fork it to your space, make some modifications, and be up and running.
First a point of clarification about GitHub Pages. The URL the GitHub creates is based on whether it is a “Project Page” or a User/Organization page. User/Organization pages follow the format username.github.io but the repo has to be called with that same format username.github.io. In a user page all work is done directly in the Master branch. The alternative are “Project Pages” which use a special branch for hosting the website information (so that ostensibly an actual software project could be hosted at the Master branch). GitHub has a page about User/Organization/Project Pages
For the purposes of this tutorial I’ll setup a Project Page. First I need to fork the repository to my own account to make any modifications to it.
Now that I have a copy of the project I’ll open up GitHub for Mac to clone a copy to my laptop. I grab the repository from my account and have it create a folder on the desktop.
Within GitHub for Mac you can change the branch you’re working in at the top. I switched to gh-pages since that’s where project pages are hosted. The next thing I need to do is open the config.yml file to add my settings. YML stands for “Yet Another Markup Language” and has become something of a standard in various places but basically it’s just a syntax for adding settings to your site. You’ll see here we’re I’ve updated quite a few settings. Of not is the URL pattern for url and baseurl which must match up with where it’s going to be hosted.
Mostly just changed the title, added some social icons. Now that the text is edited I save and move back to GitHub for Mac and it detects all of those changes. I can add a commit message and then sync it with the repository on GitHub.
Indeed if I go to the Settings directory I’ll see confirmation that the site is live at http://timmmmyboy.github.io/pixyll
And if I shoot my browser that way my new site is live. This is the first very basic intro to Jekyll, we’ll get into some more advanced scenarios in other topics. If you’re playing with this stuff I’d love you to consider writing some of it out for the benefit of the community.