HgBlog 0.5

Sphinx-based blogging engine

  Add it to your Download Basket!

 Add it to your Watch List!


Rate it!
send us
an update
BSD License 
5.0/5 1
Josh VanderLinden
ROOT \ Documentation
HgBlog contains a set of modifications to the Sphinx project to make it slightly more suitable as a blogging engine. It's built for those of us who love using reStructuredText markup to write documents.

The quickstart wizard handles setting up an HgBlog for you. This includes all of the usual things that the Sphinx quickstart utility does, but it creates a Mercurial repository and installs a hook and intelligent ignores for you. The hook will automatically convert the .rst files that Mercurial is tracking into HTML using Sphinx when you commit changes to the repository.

Additionally, when you pull changes in from a remote clone of the repository, the hook will do the conversion just like when you commit locally. You can set the hook up on remote clones as well. The hook only converts .rst files that are tracked by Mercurial. This means you can work on new blog articles without committing them to the repository to have them not appear online.

Why?? Aren't There Enough Blog Engines Already?

Yes, there are. And most of them rely on databases that require regular maintenance and backup. Databases can also slow down your blog. HgBlog offers you a way to serve up your blog articles as static HTML without the overhead of requesting an object from a database, making it fit into a layout, etc. Any webserver should be perfectly capable of serving the content generated by HgBlog.

I'm not saying there's anything wrong with database-backed blogs. I maintain my own blog that is Django powered (and database-backed). It works fine for me. However, some people might not want to be confined to the rules imposed by a full-on blogging engine (whatever they may be). People have all sorts of reasons for doing things differently. Some people don't need a reason at all. It boils down to what works for you.

What does HgBlog offer you that should be attractive?

 * Speed. No need to deal with the formatting headaches of whatever WYSIWYG editor your blogging engine has dictated is the best. Just use reStructuredText markup (which is quite easy to learn if you've never used it before) and let Sphinx worry about formatting it.

 * Consistency. Again, reStructuredText is a very simple format that will produce consistent, nicely-formatted documents.

 * Portability. Since HgBlog generates static HTML, you can put it on any server. In fact, you don't even need any server software--just a web browser. Also, Sphinx allows you to export your articles in several formats:

- HTML, multiple files
- HTML, single file
- epub
- LaTeX
- Plain text
- man pages

 With other tools, you can even turn your .rst files into PDF or ODT documents.
* Redundancy. Since every article you want to have on your blog must be checked into Mercurial, a distributed version control system. This means that you can easily clone your blog to another system, which is a very fast and effective way to backup your articles. If the primary "server" for your blog ever dies, you are likely to have at least one full, up-to-date backup of your blog if you're using Mercurial as it's designed.


I've developed and tested HgBlog using Linux, Python 2.6.4, Mercurial 1.5.1, Sphinx 1.0-pre, docutils 0.6, Jinja2 2.4.1, and Pygments 1.3.1. However, Sphinx suggests the following version requirements. I'm just being safe with my requirement on Mercurial's version.

 * Python 2.4+
 * docutils 0.4+
 * Jinja2 2.2+
 * Pygments 0.8+
 * Mercurial 1.5+


There are several ways to install HgBlog:

 * Using pip (recommended):

 pip install -U hgblog

 * Using easy_install:

 easy_install hgblog

 * From the CheeseShop

- Download the .tar.gz file from PyPI
- Extract the .tar.gz file
- Run python setup.py install using the setup.py in the extracted directory

 * Using Mercurial:

 hg qclone http://bitbucket.org/codekoala/hgblog
 cd hgblog
 hg qapply -a
 python setup.py install

Last updated on June 8th, 2010


#blogging engine #write documents #Sphinx #blogging #engine #documents

Add your review!