hgblog 0.3

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

  • LaTeX PDF

  • 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.

Possible Workflows

• You have a server which offers Python and SSH access, and you’re allowed to install your own software within your home directory (or you have full root access to install elsewhere). Run the quickstart utility on your server, clone the repository onto your local machine, write articles, commit them, push them up to your server. When you’re ready for those articles to appear online, simply run hg up on the repository on your server. Make sure your webserver software is configured to serve static content from your build/html directory.

• Use HgBlog to produce your own, personal wiki. Keep notes on things you do at work or projects you’re currently working on.

• Don’t have a server that supports ASP, PHP, Ruby, Python, or whatever language you prefer? Use HgBlog to compose your articles locally, commit changes to the .rst files, and use an FTP program to upload the HTML files to your hosting provider.

Requirements

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+

Installation

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

Getting Started

HgBlog leverages the existing quickstart wizard for Sphinx projects. There are some modifications to reduce the number of steps required, so you should be able to be up and running within a minute using:

hgblog-quickstart

All you need to do is:

• Provide the directory on your filesystem that shall be used for your blogging needs.

• Provide a name for your blog

• Provide your name

• Select any extensions you may want to include in your blog

Once you do that, you should have a few new directories, one of which will be called source. This is where you should write your .rst articles. When you’re done working on a particular article, you can use:

hg add
hg ci

…to add and commit it to your Mercurial repository. At this point, Sphinx will be asked to generate the HTML for your blog based on your .rst files.

If you feel like using Mercurial to clone your blog articles to another system, you might be interested in adding to the new repository the same hooks that are installed by the quickstart utility. First off, this requires HgBlog to be installed on the other system. Next, edit the .hg/hgrc file for the new repository:

[hooks]
update.hgblog = python:hgblog.generate_html.htmlize_articles
commit.hgblog = python:hgblog.generate_html.htmlize_articles

These hooks make it so the HTML version of your pages will be generated each time you commit changes to the local repository and each time you update your local repository using changesets pulled in from elsewhere.

hgblog-refresh

TODOs

• Add RSS feeds