Sunday, 4 September 2011

Markdown in Blogger

I'd been avoiding blogger for while because I like neither wysiwyg
editors nor raw HTML.  I find wysiwyg annoying because I never know
what the editor is doing and what sort of weird codes it is inserting
which will come back and bite me later.  I find HTML has a horrible
authoring user experience: it is way too easy to forget to close some
tags and end up with non-conforming HTML.

I have been a fan of
[Markdown]( for many
years. I find its light weight mark up to be very good for authoring
content.  Wordpress has long supported markdown but it wasn't right
for me: the free hosted service couldn't support vanity
domains properly (and doesn't include the markdown plug in); I don't
write enough in my blog to justify paying for hosted Wordpress; and I
didn't fancy running my own web server with Wordpress (and its
security updates).  What I really wanted was Markdown support in
Blogger which offered free hosted blogs with support for vanity

My investigations into existing options found solutions which only
really solved the problem for post creation rather than authoring in
general which includes editing.  Typically, they were along the lines

  1. write blog post in markdown
  2. convert (and save) as HTML
  3. publish.

The problem now is that the post is in its converted form which means
you cannot edit the post in its original markdown syntax any more.

Instead, I decided to "roll my own" (well, reuse what exists out there
to do it my way).  The basic idea is:

   1. write and save post in markdown syntax between `pre` tags
   2. convert markdown syntax on the client-side using a javascript
      markdown implementation.

Now, if you happened to be using a browser that doesn't support
javascript, at worst you'd have an unrendered post in markdown syntax
which thankfully is quite readable already.

Fortunately, most of the hard work had already been done by
which is a javascript port of a markdown.  I just took showdown and
plumbed it together with some more javascript which

   1. finds `pre` elements marked with `class='markdown'`
   2. call showdown to convert their contents into html and inject
      that back into the post inside a `div`.

It was a actually a bit trickier than I had first thought.  I'd had to
fight to check it worked in a reasonably recent version of IE which
always seemed to behave differently from the other browsers (Chrome,
Safari and Firefox).  I also fell into some weird javascript holes
(yeah, my javascript-fu mostly sucks).

The result is a .js file which you use by adding one `script` tag to
your Blog template.  It's still work in progress so I'll hold off
sharing the code (properly) until I think it's ready.

There is one major caveat.  Though I am now freed from the tyranny of
angle brackets and matching open and close tags, I still have to make
sure I escape special characters such as <, > and
& since the content of the `pre` tag still has to be html.

This article is written in markdown.  What do you think?


dhanz ramadhan said...

thank for share :)

Jose Marcenaro said...

Hi Francis
Thanks for sharing the idea and obstacles you've found.
Is the .js code working? In that case may you share it too?


Daniel Dotsenko said...

I gave Markdown on Blogger a stab as well. Works with some gotchas. Code available.

Francis Tang said...

Thank you all for your comments. I hadn't been paying attention to this blog and hadn't noticed your comments!

To address the last two comments, I believe the .js code is working. I was holding back partly because I was looking for an appropriate static file hosting service. I've now put the files on a Google App Engine app for the time being. Feel free to view-source this blog and copy the script tag at the end of the page.

I had a glance at Daniel's blog post; very nice! I had also considered using script tags rather than pre tags. I believe the advantage of the latter is that it has a better "degraded mode" experience. If the browser doesn't support javascript or the user has it disabled, it still renders as markdown syntax.

Of course, the side effect of using the pre tag over the script tag is that you have to escape < and >. Also, the Atom feed shows the unrendered markdown syntax.

Richard Kuo said...

I just got a Byword for publishing to Blogger and have both Mou and Byword point to the same file while I am writing.

John Doe said...

Hello Francis, it looks your method is the easiest, however I failed to blog by markdown. Although I had quoted your js file in the template, and put 《pre class="markdown"》 some words here《/pre》 into the the post. It would be nice if you could give me some advice.

Divya van Mahajan said...

Hi Francis,
Thanks for your post. I took your thinking and created a updated variation. See