Short Status Review for Technical Blog

Markdown syntax is really helpful when you need to create structured text. I'm having a lot of problems in the WYSIWYG-Editors of all the blog portals when dealing with tags, escaping and code blocks. For example wanting to talk about the [sourcecode] tag and later having an actual [sourcecode] ... [/sourcecode] listing will not work in Wordpress. A nice article about the dilemma with WYSIWYG-Editors can be found here.

In Markdown you simply indent the sourcecode by 4 spaces and don't need to worry about escaping characters or tags. As the Markdown Reference puts it nicely:

This makes it very easy to include example HTML source code using Markdown. [...] Regular Markdown syntax is not processed within code blocks. E.g., asterisks are just literal asterisks within a code block. This means it’s also easy to use Markdown to write about Markdown’s own syntax.

The only downside is that in standard Markdown you cannot add the class for syntax highlighting on the <pre> that is generated. Instead of indenting you could also go with a "plain" HTML block:

<pre class="brush: javascript">
    for(var i=0; i<n; i++){
      bounds.extend(markers[i].getPosition());
    });
</pre>

Unfortunately this doesn't work as the less-sign is not automatically converted to its HTML entity because within a HTML block no markdown parsing is made.

In the simplest workaround you would simply replace all ampersands and brackets with the verbose HTML entities. But this kind of defeats Markdown's philosophy of being as easy-to-read and easy-to-write as feasible. So I will take a look at some of Markdown's dialects and extensions, like Maruku, as well as other lightweigt markup languages like Textile.

Chosing a Technical Blogging Portal

Recently I have thought of creating an extra blog for the more technical stuff I post, i.e. program listings and solutions to problems. Those kind of posts usually include some source code that I want to be displayed as preformated text and with syntax highlighting. So I looked at the source code posting features of three of the most popular blogging platforms:

• Blogger.com
• WordPress.com
• Posterous.com

What I did in Blogger so far (as you can see in my older posts) is to simply change the font type to Courier and decrease the font size. That kind of works for small listings, but doesn't look pretty. It get's really messy when you try to post longer lines of source code though. To improve things and get syntax highlighting working what you can do is modify the header part of your template to include a javascript highlighter. Alex Gorbatchev's SyntaxHighlighter seems to be a very popular choice. It is self contained, brings 23 Syntaxes with it and is used by big players like Apache, Yahoo and even Wordpress.

Following the installation instructions you must do the following to get it running reference the core javascript, css and theme files (3 lines) references all the syntaxes that you need (up to 23 lines) set blogger.com mode (and other default mode) and then call the syntax highlighter javascript function (>=2 lines) The large number of lines may seem intimidating at first, but it's pretty much just javascript and css references and you don't need all the files. The actual source code is then embedded in pre or javascript tags. Customization parameters can be passed class values on that tag.

As mentioned above WordPress.com includes Alex Gorbatchev's Syntax higlighter by default, which is nice; the usage is even simplified as instead of using the above HTML tags you can just wrap your source code in [sourcecode] tags where you also put some the options. Take a look at the support page. Example:

    [sourcecode]
    This is a short snippit of code with padlinenumbers set to 4.
    [/sourcecode]

Pretty neat and not as verbose as using pure HTML. Posterous goes a similar way, but seems to have problems with line spacing. And the HTMl editor is really not that usable, especially if you created a blog by E-Mail. But Posterous supports markdown syntax out of the box now, which is kinda neat; you just have to wrap the (markdown) content in tags. That let's you embed source code in "regular" markdown syntax by indenting it (pitfall: at least 4 spaces for posterous). Language is set up with a she-bang. So you would have:

    #!c++
    void main(){
      cout << "hello world!";
    }

As mentioned before, though, the HTML editor is a pain to use and won't work if you sent your markdown by E-Mail; I think it's a bug. Still having the markdown option built-in is nice. Blogger.com and WordPress.com won't allow you to write your posts in markdown.

In conclusion, SyntaxHighlighter seems to provide very nice looking code listings and gives you a lot of configuration options. If you don't want to mess with the HTML of your layout files go with WordPress.com that gives you easier access to it. If you want to write markdown online or in the email your only choice seems to be Posterous. But if you can live with writing your markdown and running it through a HTML converter you could use every blogging service here. Overall Wordpress.com seems to be the winner for maintaining a technical blog. So I probably will be looking into Wordpress for my technical blog that I plan to create. Opinions?

Colophon

I have added the above mentioned changes to my blogger template and used markdown to reformat this blog, parse it and then paste the HTML. My "source" markdown looks as follows:

<pre class="brush: c++">
    void main(){
      cout << "hello world!";
    }
</pre>