In my last post I described installing Ruby on Mac OS X with RVM. The main reason I wanted to do this was to run a Jekyll Blog using GitHub Pages. So, in this post I will guide you through the process to get a GitHub Pages Blog up and going.
1. Installing Python and Pygments with Homebrew
Since we already have Homebrew installed, we can install the Pygments Python Egg rather easily and get some beautiful syntax highlighting for your code posts.
In your terminal execute the following to install Python using Homebrew:
brew install pythonAfter it's completed, add the following line to your .profile file located at ~/.profile (or /Users/you-user-name/.profile):
export PATH="/usr/local/share/python:${PATH}"Save it and run:
source ~/.profileYou can also close your terminal and re-open it instead.
Confirm you are using Homebrew's Python and not your system Python:
which pythonIt should output the following (assuming default Homebrew setup):
/usr/local/bin/pythonMake sure pip is installed and replace setup tools with distribute (an alternative to setuptools):
easy_install pip
pip install --upgrade distribute
Finally, install pygments:
pip install pygmentsOnto the next step.
2. Install Jekyll
Assuming you followed the directions in my last post about installing Ruby with RVM and you have it set as your default Ruby you should be able to execute the following command without any errors:
gem install jekyll3. Setup GitHub Repo
Sign up, login, or go to your GitHub account and create a new repo starting with your username, for example, I created a repo called:
chriskaukis.github.com because my username on GitHub is chriskaukis.
The create new repo link is at the very top right of the page.
4. Clone Your Repo
Clone your repo by executing the following command:
git clone https://github.com/[your-username]/[your-username].github.comBut replace your [your-username] with your username (without the brackets).
This is your GitHub pages blog repository now. Lets set it up with some of the minimal content needed to run.
5. Initial Jekyll Configuration and Setup
At the bare minimum you will want the following files in the root of your repository:
_config.yml (Jekyll uses this for setting custom configuration options.)
.gitignore (Tells git to ignore certain files.)
README (GitHub uses this for your "main" repo page. Do not confuse with your blog page.)
index.html (Your base blog template.)
You will also want the following directories:
_layouts
_posts
_site
To keep this simple and get you up and running fast I'm going to give you an example of each file above with some minimal content.
_config.yml
safe: true
source: .
destination: ./_site
lsi: false
pygments: true
.gitignore
_site/
.DS_Store
README.md (or README. You can change the text. The .md extension means Markdown.)
## GitHub Pages Blog Repository ##
This is the repo for my blog.
index.html
---
layout: default
title: Christopher Kaukis's Blog
---
<h2>Posts</h2>
<ul class="posts">
{% for post in site.posts %}
<li><span>{{ post.date | date_to_string }}</span> » <a href="{{ post.url }}">{{ post.title }}</a></li>
{% endfor %}
</ul>
Note: In this file the content between between the --- and --- are for Jekyll to know the title of the page and the layout to use. The layout is the name of the layout file in _layouts, which we will get to shortly.
Now we need to create a default layout file and a layout for your posts. Finally, we will create your first post and push it to your repo.
In your _layouts directory create a file called layout.html with the following text:
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>{{ page.title }}</title>
</head>
<body>
<h1>My Blog</h1>
<div id="main_content">
{{ content }}
</div>
</body>
</html>
Also, in your _layouts directory create another file called post.html with the following text:
---
layout: default
---
<div id="post">
{{ content }}
</div>
6. Create Your First Post
Finally, we are the point of making our first post.
In the _posts directory create a file with the following format for the name: "yyyy-mm-dd-post-title.md". For example: 2013-03-10-first-post.md and put the following text in this file:
---
layout: post
title: First Post
---
First post!
7. Test
Now, test your blog before pushing your changes and post. Run the following command:
jekyllFollowed by:
jekyll --serverNow in your browser go to: http://localhost:4000
You should see your page! If it worked you can add your files to your repo by executing the following:
git add .
git commit -m ‘My first post.’
and to push it live:
git push origin master8. CNAME (Optional)
If you own your own domain and would like to have a non-GitHub URL you can create a CNAME file in the root of your repo with the URL you would like. For example, I own kaukis.com and in my CNAME file I put "chris.kaukis.com". Then at my DNS host, I added a new CNAME for this record with chriskaukis.github.com.
Here is an example screenshot from my Namecheap.com account where I host my DNS:
Now, after all that, you should have a Jekyll blog. Here is mine: http://chris.kaukis.com
9. Workflow and Other Stuff
First, I highly recommend you read through the wiki: https://github.com/mojombo/jekyll/wiki
Check out the example sites, peruse the plugins, and other things you can do with Jekyll.
To add a new post it’s very simple. Create a new file with the name and format I described above. Use the git add command and git commit. Then test it and if all is good push it live.
If you have any specific questions or requests, I can try and help or maybe write a post on it soon.
If you have any questions or have problems, post a comment below and I’ll try and help you. I hope this post was helpful.