Clone wiki

blog / Home

Blogging for the rest of us

Purpose: Author and maintain your as text-files in your favourite source control management tool.

While there are certainly a lot of good blogging tools and services available, as far as I know all of them fail to provide all of the following at the same time:

  • Free and robust hosting
  • Ownership of the blog contents in an available format (databases can be quite obscure)
  • Proper revision control
  • Markdown syntax (important to me)

This project aims to remedy this situation.

Additionally, this project tries to make it easy to author a blog along with developing a programming project. I find this useful as a powerful sort of rubber ducking. You even get to have a potential audience!


You need Mercurial (sudo apt-get install mercurial, for example)

Then, from a suitable directory:

    hg clone
    cd blog
    cat # Consider what this script does, then

Now, you should have the command blog available to you.

If you want to help, I would appreciate tips on how to create a .deb-package for this. (See #1)

Example session

Start a brand new project:

    ~/prog$ mkdir my_new_project
    ~/prog$ cd my_new_project/

Now, establish a blog for this project:

    ~/prog/my_new_project$ blog init
    Now use "blog add" to add a blog entry!

Uhh... okay.

    ~/prog/my_new_project$ blog add

At this point, an editor pops up and you can write your blog entry in Markdown syntax. You can specify which editor to use in the EDITOR environmental variable. The first line of your blog entry must be the title of the entry, in this case "Welcome".

    Wrote /home/mag/prog/my_new_project/blog/

Then comes the magic -- publishing to You will be asked for the things blog needs to know the first time you do this. The necessary values will be remembered and due to Google's Data API this does not include your password. The values will be stored in ~/.blog.user and .blog.

As of now you need to create the blog you want to publish to over at yourself first. (See #2)

By default, will turn all newline characters into <br/> tags. This is bad mojo. To avoid it, go to the web interface at, find the "Settings" for your chosen blog, select the "Formatting"-page and set "Convert line breaks" to "No".

    ~/prog/my_new_project$ blog publish
    Google ID: my_blogger_id
    Password for Google ID "my_blogger_id":
     [0] my new project
     [...] my other blogs
    Please choose which blog to publish to: 0
    This is a dry run. Nothing will be sent to
    Use command line argument --write to disable dry run

blog publish will only show you what it wants to do. If this seems agreeable, run blog publish --write (or blog publish -w):

    ~/prog/my_new_project$ blog publish --write
    This is not a dry run. Updates will happen

VoilĂ ! Notice that the second time, blog publish doesn't need you to answer any questions.


Due to a known issue in python-gdata (Google's Data API library for Python), this warning can appear when running blog:

DeprecationWarning: the sha module is deprecated; use the hashlib module instead

This is harmless and will disappear with the fixed version of python-gdata.


This has been tested and found working on Ubuntu 9.04 and 9.10.

However, at its core it is fairly cross-platform compatible Python, so it should be fairly easy to make it work even on significantly different platforms.

Possible short term improvements

  • #1: Proper packaging (possibly for things other than Ubuntu, but that's not important to me)
  • A choice of interfaces, for example a KDialog-based one, but most importantly an internal SPI for realizing it
  • Consider the security implications of storing the authentication token in plain text in a file readable to all users (if you care, you probably want to chmod 0600 ~/.blog.user)
  • Possibility to dump a to disk and continue blogging to it -- to change workflow from web-based to bftrou-based
  • Interactive mode for blog publish, so it doesn't have to evaluate everything twice