Just the other day, I decided to setup blogging on my Github Pages page, jeffwelling.github.com . It took me longer than I feel was really necessary to get going and one of the most frustrating things, despite the copious amount of docs out there already, was that I really couldn’t find much information on how to use jekyll (aside from how to use it to host the blog from jekyll itself).
Some really good material to help get you oriented
There are many pages and docs out there but few, if any of them were aimed at someone who wasn’t only new to jekyll but who was kind of new to blogging too; I wasn’t aware of any blogger terminology or best practices or even common practices. This blog post is intended to help people in the situation that I was in, you want to start blogging with Github Pages, Jekyll and Disqus for comments but you don’t know what to do or how to approach this, or you read the jekyll documentation and were still left feeling a bit mystified on how to use the thing.
First and foremost, you will need an account on Github.com which is where your blog will be hosted. Your jekyll blog doesn’t have to be located on Github, but it is the method chosen to be covered in this blog. For information on hosting it elsewhere, realize that the _site folder is all you need to copy to your web server, and just Google for jekyll documentation.
The Github Signup page has several plans, but I just chose the free one for now. If your blog gains a lot of traffic you aught to consider upgrading to a pay account, even if for no other reason than to help support the people who are hosting your blog.
Now that we have a Github account, we can create a repository that will host our blog.
One of the neat features about Github is that if you create a repository called NAME.github.com where NAME is your Github username, then it will be published as a Github Pages website at http://NAME.github.com/ . My Github username is jeffwelling, following that link will take you to my main blog page and you can see in the address bar what I mean.
For more information on how you can work with Github Pages and create project specific blogs etc using the gh-pages branch in your project’s repo, see this and more importantly, this . I won’t be covering it in this blog post.
Now, we have our Github Pages page setup for our user at NAME.github.com . The next step is to install jekyll and start blogging.
There is a Ruby Gem called jekyll_generator which will help you create an empty blog directory.
I wanted to create and store my blog in my ~/Documents/Blog directory, so I did
$ cd ~/Documents
$ /var/lib/gems/1.8/bin/jekyll_generator Blog --title "My Musings"
I had to call it by the full path for some reason, ‘Blog’ is the directory that it will create and put the new empty templates and stuff in, and “My Musings” is the title of my blog in case you hadn’t noticed you insensitive clod!
At this point, you may want to run
$ git init
$ git add .
$ git commit -a -m "Initial commit"
Just so that you can return to this clean state if you accidentally muck something up.
This is where I started to get confused though. I had an empty blog directory, but how did I create a post?
The answer is easy, you just start writing a textfile. If you want it to look pretty, check out Textile and Markup . Also, remember, if your going to use Textile or Markdown make sure you save it with the appropriate extension, .textile and .markdown . Where you save the file, and what you name it is the critical part here in making it a blog post.
When your posting, your post must be saved into the ~/Documents/Blog/_posts directory, and it must have the name format of year-month-day-the-title-of-the-post.format .
By saving the text file in the _posts directory, with that specific name format, you will have created your blog post.
If the name format still confuses you, take a look at my _posts directory. Currently there are only a handful of posts, but they were all created on October 13th 2009, and so all three of them begin with “2009-10-13” and they all end with either “.textile” or “.markdown” to indicate which markup to use. The actual title of the post itself, is stored at the top of the file in a section that looks like this;
Now, to publish your blog post on Github, you git add your post from the _posts dir, and git commit it, and then git push origin to push it to Github. Its important to remember that in your git repository, your _site dir should be empty. If you are running jekyll locally on your computer then you may want to simply add _site to your .gitignore file. I made the mistake of running jekyll locally to preview the blog post, and then adding the files in _site to my git repository. The result was that when I pushed to Github, Github wasn’t updating my blog properly.
In this case, the title of the blog post is “Ruby’s splat operator”. To be honest I’m not sure if there is a direct relationship between what you put in the filename as your title and what you specify in that short blip at the beginning of the post as your title, if anyone knows what the connection is please comment on it.
If you haven’t already done so, you need to initialize your .git repository, and add everything under ~/Documents/Blog/ to it (as per our example above, if you use a different directory then obviously change it to accommodate).
Now, if you haven’t already done so, you need to setup your git repository so that you can push to Github to publish your blog on Github Pages by adding an ‘origin’ reference which points to Github. This is outlined on the Github page when you first create your repository. For example, for me and my blog, the commands were
$ git remote add origin \ git@github.com:jeffWelling/jeffWelling.github.com.git
$ git push origin master
But you will need to change the user name from jeffWelling to your user name if your going to copy/paste that command.
Now, you should have a blog hosted on Github Pages using jekyll. In order to get Disqus comments on your blog, keep reading. Otherwise you can stop here and be content with your comment-less blog.
Using Disqus comments on your blog is as easy as creating a Disqus account, pointing it at your blog, and adding a couple lines of source to your default layout files in the “~/Documents/Blog/_layouts” directory. I would copy and paste the lines for Disqus but the lines that they give you to copy are customized per your blog so it will just be easier to tell you to copy and paste what they give you instead. Note that unfortunately jekyll_generator tries to be friendly and generate the necessary Disqus code for you, but it doesn’t seem to do it correctly. I had to manually remove all of the Disqus code, and replace it with the code that I copied dierctly from the Disqus Install Instructions Universal Code section. If you used jekyll_generator you may have to do the same.
That should be it, now after running jekyll, commiting and pushing your changes to Github, you should have a wonderful new blog, optionally complete with comments as well!
How do you create a new post with jekyll?
Create a new file in the _posts directory with the appropriate date and title information in the name as specified above. Fill it in with your blog text, and accompanying markup if you like. Then, run jekyll in the top level blog directory, in my case ~/Documents/Blog . This will update all the necessary files in _site . Now, you can do a
$ git add
to add any new files/posts,
$ git commit
to commit your changes, and finally
$ git push origin
to push your changes to the server and publish them.
Now, if you’ve followed the instructions in this blog, you should have a working Github hosted, jekyll generated, Disqus enabled, git revisioned blog.
Questions? Suggestions? Did I miss something? Did it not work for you?
Leave a comment and let me know!
Cheers.
