Django Techblog markup system

Django Tech Blog is now running my blog. It is only fitting that my first post on the new system is about the technology behind it.

I never intended to compete with Wordpress on number of features, and Techblog was never intended to be an all-things-to-everyone type of web application, but I can boast a few features that set it apart. I'll cover some of those features in future posts, for now I would like to go over the light-weight markup language I use for posts.

I've noticed that when working on ITProPortal.com, and other content driven sites, that adding additional content to a page was always a major under-taking. Adding a new content area to a page typically required adding a field to the model and some interface work. I figured it would be nice to build a generic system where the various pieces of content are stored in a single field in the database and created as required.

I guess that XML would be the obvious choice for such a system, but writing XML is best left to machines – in my opinion. Rather, I settled on a simple markup that I call extended-postmarkup.

In an extended-markup post, the text is divided up in to sections, which are ultimately transformed in to HTML and inserted in the page. Each section consists of one or more chunks, which are a collection of lines that are passed through a specified Django template. The default chunk template passes the lines to a bbcode filter and turns each line in to a paragraph, but any other kind of text processing could be done.

A line in the markup is parsed as an extended-markup directive if it begins with a { character and ends with a } character. A new section is introduced with a directive that begins with a . character followed by the name of the section, chunks are introduced with two . characters. The name of a chunk maps directly to the name of a Django template. For instance the {..code} chunk directive causes the subsequent lines to be rendered with markupchunks/code.html which does syntax highlighting.

Here's an example of some simple extended markup:

{.main}

This is the [b]main body[/b] of the post, and will be turned in to paragraphs.



{..code}

{..language=python}

print "Hello, World!"



{..}

Back to paragraphs again.



{..html}

<blink>There is also raw HTML if you must!</blink>



{.column2}

This goes in the second column.



{.footer}

This goes in the footer.

The code above introduces some other abilities of extended markup. The {..language=python} directive sets a chunk variable, which is also passed to the chunk template; in the code above it is the name of the language to do syntax highlighting, but there can be any number of key/value pairs set for chunks. There is also a chunk directive with no name ( {..} ), this sets the chunk type back to the default.

… this simple system means I can create ad-hoc features in a post such as pull-quotes

That's all there is to authoring extended-markup, but this simple system means I can create ad-hoc features in a post such as pull-quotes, and even use different markups such as markdownand reStructuredText.

Here is another example, used in this post to create the list of links you should be able to see at the top of the right-hand column.

{..linkslist}

{..priority=200}

{..title=An example links list}

My blog|http://www.willmcgugan.com

Planet Python|http://planet.python.org

The markup is not limited to the visible parts of the site; in this blog there are sections marked out for CSS and Javascript, so I can make style tweaks and demonstrate Javascript techniques without having to link to an external page. This is a techblog after all…

If you want to play with the code, head over to the django-techblogproject page on Google Code. It is completely lacking in documentation or comments, but that may improve in the future.

That's all for now, I'll write up more techblog features in the coming days. I'll also be doing a lot more blogging on other topics, as I need to be able to justify to myself, spending 4 months of spare-time on this!