A lot of tech bloggers will write their blog posts in Markdown, convert it to HTML and paste that HTML into their blog of choice and then in the blog’s editor clean it up to suit their blog. This is an excellent way to create easy to read portable documents that can easily be published in multiple formats.
However what if there was a way to skip the second part of that and just create a markdown page, submit it into your source control ( you do use source control right? ) and your blog would automagically update.
In comes Octopress, it’s a framework that wraps around Jekyll which is Github’s blogging engine that powers Github Pages. Essentially you edit Markdown files and Octopress will compile it into a static-html Jekyll blog. This means that your blog will be lightning fast ( no need to run an interpreted language in your web server ) and ultra portable.
Another side benefit is that you can host it for free on Github ( as long as you’re okay with sharing your source … and you should be! ) or for free on Heroku ( don’t have to share your source ) or host it on any simple no frills Apache, LightHTTP, nginx, node.js, etc server.
Here is how I’m porting my blogger site to Octopress hosted on Github Pages. I’m not using any of the fancy Jekyll migration tools as I only have a few posts and it will help me get used to the extended syntax that Octopress uses in Markdown.
As usual the first step is to install any dependencies. These instructions are for Ubuntu 12.10 … modify to suit your OS of choice.
Most of these steps are taken directly from the Octopress Documentation, I’m just condensing them into a single document to suit the exact scenario being described in this post.
Check your Ruby version is at least 1.9.3 and install bundler:
ruby --version sudo gem install bundler
Clone the octopress repository and set it up
git clone git://github.com/imathis/octopress.git octopress cd octopress bundle install rake install
We’re going to use Github pages. Octopress has some rake tasks to make this easier for you. Your blog will be hosted at
http://username.github.com and you need to create a new Github repository called
username.github.com that github pages will use the master branch as the html source for your blog.
This rake points our clone to the new repistory we just set up, configures your blog’s URL and sets up a master branch in the
_deploy directory for deployment.
_config.yml and fill in your blog name and other details. There’s also some configs for twitter/G+/etc plugins that are worth configuring.
Great time to read Blogging Basics
About page and a
First Post! blog post:
rake new_page["About"] rake new_post["First Post!"]
Edit the Markdown pages that it creates for you with your preferred Markdown editor. The output of the rake commands should provide appropriate hints as to the location of the created files.
Generate and preview the blog:
rake generate rake preview
This will generate the contents of your blog and allow you to preview it at [http://localhost:4000].
Once you’re happy with the contents we can deploy your blog for the first time.
This will copy the generated files into
_deploy/, add them to git, commit and push them up to the master branch. In a few seconds you should get an email from Github telling you that your commit has been received and will be published on your site. Being your first commit it could take 10 minutes for the blog to be available at [http://username.github.com]
Don’t forget to commit your changes to the source branch:
git add . git commit -m 'Added About page and first post!' git push origin source
This is pretty simple ( assuming you have the prerequisites already install ).
If you run Dropbox you can do this inside of your dropbox folders to make this instantly avaiable on any system you use.
git clone email@example.com:username/username.github.com.git cd username.github.com git checkout source mkdir _deploy cd _deploy git init git remote add origin firstname.lastname@example.org:username/username.github.com.git git pull origin master cd ..
once this is done you can run
rake new_post["title"] and all the other rake commands needed to edit/preview/publish your blog.