24 June 2008

Markdown

The last two articles on this site, plus this one, are the first to not be written in raw HTML. Instead, they were written in a plain text format called Markdown. The text is converted to HTML whenever the pages are viewed. What seems like a small step for blogs in general is in fact a giant leap for mattryall.net.

When you have to implement every new blog feature yourself, every new feature is worth celebrating. In this case, it’s probably the biggest improvement since I moved from CSV files to a relational database back in 2004. (The extra charge for a database kept me on CSV until I changed hosting providers.) The move to Markdown frees me from having to type error-prone HTML for every post. Since I started posting more regularly, the pain of validating and fixing up every single markup or encoding errors become much more pronounced.

Markdown has the other benefit that it allows inline HTML. So if I feel the need to put in an aside with an image and a short caption, I can drop straight into the same HTML I’ve always used.

Even more pronounced than the pain of HTML errors, however, was the finickiness of trying to use correct apostrophes and quotation marks throughout my posts. Alert readers may have noticed that I started trying to use the correct typography in my posts last week. It was incredibly difficult—even with the Mac keyboard shortcuts to insert the quotation marks (Option+] and Shift+Option+])—to ensure I used the correct character in all the don’ts, isn’ts and that’ses. I ended up using the browser’s search to scan for ASCII apostrophe characters before publishing anything. I usually had ten or twelve that I had missed while writing the article.

Enter SmartyPants. This is another project by John Gruber, and takes HTML or plain text as its input. It goes through and replaces all the straight quotes with the correct rounded ones. I’ve run it over some of my posts with quite complicated HTML—tables, floated nested divs, etc.—and it just works. Now SmartyPants runs automatically over all my posts which I write with Markdown. We should probably put the same functionality into Confluence. I’m sure the algorithm isn’t terribly difficult, especially if you have the plain-text source.

Together, these two make it possible for me to churn out blogs faster than ever before. I’m a bit disappointed it took me so long to get around to implementing the article filtering that made it possible.