The Kitchin Research Group

I do most of the blogging on a Windows 7 machine. I run everything from a git Bash shell that came from http://git-scm.com/downloads, and I use the Canopy (https://www.enthought.com/products/canopy/) Python distribution.

First, we install the python modules we need.

pip install Blogofile
pip install Blogofile-blog

[2013-03-03 Sun] Update I uninstalled these packages because I wanted to modify the source code a bit. I have forked the repositories and slightly modified them to get tags working for my blog. Those repositories are at https://github.com/jkitchin/blogofile_blog and https://github.com/jkitchin/blogofile.

Blogofile has a command blogofile that sets up the directories you need to create a blog. The goal is to setup the directory structure, then setup the blog directory under git. The blog will be hosted on GitHUB. We do that that by creating a repository called <github-userid>.github.com with two branches, source and master. GitHUB will serve whatever is in the master branch at <github-userid>.githb.io. My GitHUB userid is jkitchin, so my repository name is jkitchin.github.com, and it is served at http://jkitchin.github.io[fn:4]

Locally, I want the blog content in a directory called blogofile-jkitchin.github.com. I actually have this directory in a Dropbox folder, so it synchronizes to all my computers in the office and at home. Within this directory will be a directory called _site. Blogofile ignores directories starting with _, and _site will contain the built blog content that will eventually be served. We do not want this directory under git control, because it is always generated.

Here are the commands I used to setup the initial blog.

blogofile init blogofile-jkitchin.github.com blog

cd blogofile-jkitchin.github.com
git init
git add .
git commit -m "initial commit"

echo _site > .gitignore
git add .gitignore
git commit .gitignore -m "add .gitignore"

When you are in the blogofile directory, you want to be on the source branch of the repository. This is not essential actually, but it will allow you to keep the source and built content under git control in separate branches. Next we checkout the source branch (this actually makes the source branch and checks it out).

git checkout -b source

You can build the blog now (it is essentially empty, but probably has some example posts to make sure it works). From the command line run this:

blogofile build

That creates the _site directory, but it is not under vc with git yet because we have it in the .gitignore file. _site contains all the html that makes the site. If you run

blogofile serve

You can browse to http://localhost:8080 and check out the appearance.

To get the content pushed to GitHUB, I like the following setup. I created a _deploy directory inside the root directory. I added _deploy to .gitignore so it is not under version control from the parent directory. Inside the _deploy directory, I initialized a new git repository that is on the default master branch.

mkdir _deploy
cd _deploy
git init
git add .
git commit -m "site initial commit"

For now this is all we do to configure the version control. To deploy the site, we just copy the contents of _site into _deploy, add and commit the new files, and push the master branch of _deploy to the master branch of jkitchin.github.com on GitHUB.

Currently the two repositories are local. Next, I am going to configure the two git repositories to point to my github repository. In blogofile-jkitchin.github.com and in _deploy I ran this command to point them to GitHUB:

git config remote.origin.url git@github.com:jkitchin/jkitchin.github.com

I think that is all I have done in the setup. Admittedly, these are notes partially notes I took in the installation, partially from inspection of the current setup, and partially from memory, so there may be a missing step or detail. Initially I found the setup confusing to have a git repository in an ignored folder inside a git repository, with each repository on a different branch! But eventually I got it.

Now we are ready to push the new site to GitHUB. I have a script that I run from the root directory blogofile-jkitchin.github.com with these contents.

rm -fr _deploy/*

cd _deploy

cp -R ../_site/* .

git add .
git add -u
git commit -m "deploy"
git push origin master

I delete everything in _deploy because I have not setup something more sophisticated like rsync that would synchronize _deploy and _site, deleting things in _deploy that are not in _site. That is a current limitation of my Windows setup that I have not installed rsync. I know I could, I just haven't. After that script runs, I am prompted for my GitHUB password, and it pushes the new content up to GitHUB on the master branch. If I want, I can also commit the new changes to the source branch in blogofile-jkitchin.github.com and push those changes too.

So the workflow from here is:

1. Prepare your blogpost in the _posts directory (See this post for how I do that)
2. Run "blogofile build" in the root blog directory
3. Run "blogofile serve" and check it out on http://localhost:8080 if you want
4. Run the deploy script to push it to GitHUB
5. Wait a minute or two, and checkout your new post at the github site (http://jkitchin.github.io for me)

That works pretty well for me.

Blogofile uses mako templates to generate the pages. You can see the changes I have made to the default blogofile setup and templates to customize my blog at https://github.com/jkitchin/jkitchin.github.com/tree/source, including some other automation attempts with makefiles and fabric.

I hope you find this useful!