Starting a new blog with jekyll and github
I’m renewing my efforts to generate and publish more code. Here are the steps I took to build a blog with jekyll and free hosting at github. I was brand new to both, so I had to start at the beginning. Here is some more info if you’re unfamiliar with Github Pages and Jekyll.
Github
Create an account at https://github.com/.
On your github dashboard, create a new repository called USERNAME.github.com
Use the following steps to generate an ssh key for pushing to github: http://help.github.com/mac-set-up-git/.
Locally, I created a new folder to host my site:
mkdir USERNAME.github.com
cd USERNAME.github.com
git init
touch README
git add README
git commit -m "Initial commit"
To publish to the github repo, setup the remote and push:
git remote add origin [email protected]:USERNAME/USERNAME.github.com.git
git push origin master
After a few minutes, your code will be live at http://USERNAME.github.com/.
By default, you’ll get a notification (and email) once the page is built. I found this a little excessive and chose to disable emails for “Successful Page Builds” at https://github.com/settings/notifications.
If you’re interested in using your own domain name, create a file called CNAME in the root of your repo with your desired name:
chrislunsford.com
Once that’s done, add an A record at your registrar/DNS provider to point to 204.232.175.78.
Jekyll
Github Pages supports jekyll out of the box.
Installation
You’ll probably want to install jekyll locally for testing. In my case, I was missing a few dependencies. Here’s the meandering path I took on OS X 10.7.3 (updated a few times from lessons learned):
- Install RVM
bash -s stable < <(curl -s https://raw.github.com/wayneeseguin/rvm/master/binscripts/rvm-installer)
- Update Xcode to 4.3.2
- Install command-line tools for Xcode (Open Xcode -> Preferences -> Downloads)
- Use RVM to install ruby
rvm install 1.9.3
rvm use 1.9.3 --default
- Install jekyll gem
sudo gem install jekyll
Configuration
Once it’s installed, you’ll need to build out the file structure. There are a few methods available:
- JekyllBootstrap
- Cloning someone else’s jekyll repository
- Create the files/folders yourself
I ended up building it out myself, it’s pretty straightforward:
_config.yml //jekyll configuration
_drafts/ //draft posts (not required)
_layouts/ //layout templates
default.html //default template
_posts/ //.md files
_site/ //jekyll will put generated html here
css/ //css files (not required)
index.html
Before the commit and push, create a .gitignore file:
_drafts/ //prevent jekyll from parsing your draft posts
_site/ //these are the generated html files, github-jekyll will build this on its own
DS_Store* //on a mac
Generate Content
Once the structure is setup, markdown files can be dropped into the posts/ directory. Each post should have a YML front-matter section. Full specs for this section are on the jekyll site:
---
layout: default
title: Your Post Title
---
Below the front-matter is your content. Reference the markdown basics page for help on formatting.
Run jekyll locally for testing:
jekyll #one-time command to parse files and generate your site
jekyll --server --auto #parse and server files at localhost:4000, automatically re-parse when changes are detected
Once you’re ready to send to github:
git add .
git commit -m "Commit Details"
git push origin master
Syntax Highlighting
Github Pages uses pygments for syntax highlighting. You can install pygments locally for testing:
sudo easy_install Pygments
In your markdown files, enclose your code blocks with the highlight liquid tags. You can find a list of supported languages on their site.
{% highlight javascript %}
//some javascript
var foo = function(x) {
return x * x;
}
{% endhighlight %}
The template tags will wrap the block in div, pre, and code tags with the appropriate classes. You’ll need to drop a stylesheet with your preferred styles into your css folder. Pygments comes with a few built-in styles available. You can preview these styles, grab some pre-generated css files, or run pygmentize yourself to generate the css.
I’m using monokai with a few modifications for styling on this site:
pygmentize -f html -S monokai -a .highlight > monokai.css
Changelog
- 05-04-12 - Updated jekyll install procedure, added content generation details