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.
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:
To publish to the github repo, setup the remote and push:
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:
Once that’s done, add an A record at your registrar/DNS provider to point to 126.96.36.199.
Github Pages supports jekyll out of the box.
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
- Update Xcode to 4.3.2
- Install command-line tools for Xcode (Open Xcode -> Preferences -> Downloads)
- Use RVM to install ruby
- Install jekyll gem
Once it’s installed, you’ll need to build out the file structure. There are a few methods available:
- Cloning someone else’s jekyll repository
- Create the files/folders yourself
I ended up building it out myself, it’s pretty straightforward:
Before the commit and push, create a .gitignore file:
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:
Below the front-matter is your content. Reference the markdown basics page for help on formatting.
Run jekyll locally for testing:
Once you’re ready to send to github:
Github Pages uses pygments for syntax highlighting. You can install pygments locally for testing:
In your markdown files, enclose your code blocks with the highlight liquid tags. You can find a list of supported languages on their site.
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:
- 05-04-12 - Updated jekyll install procedure, added content generation details