Markdown

Whoops! I wrote Markdown.cgi so I could easily preview Markdown content in BBEdit, but 1.2 broke this. As a fix, instead of using .markdown for source and .text to see the HTML output, v1.3 goes back to using .text files, and now ?markdown appended to the URL returns the Markdown source.

I considered allowing additional query arguments, but Apple's sh and expr string matching is quite limited, and I don't want to make the whole thing any slower or more complicated than necessary. Fortunately, it would be easy to change the 'magic' query string. Just change the 'markdown' literal on line 7.

I also moved the downloadable (.txt) script, to make the older versions available, and so I can avoid pointing people to old versions.

Almost immediately after I announced Markdown.cgi, Adam pointed out that it was now impossible to get the source of a Markdown file, since the CGI was automatically rendering the files to XHTML.

To fix this, I have renamed my Markdown source files from .text to .markdown, and made the CGI look for .markdown files, instead of using the .text filename supplied in the URL. This minor change means the source is now available as .markdown, while the HTML version is available as .text. The Apache configuration does not have to change at all.

Additionally, I updated the comments to mention that Markdown.pl requires blank lines between block elements, so one should follow the initial title line.

The new version of Markdown.cgi is v1.2. You can download and rename Markdown.txt, but here it is for reference:

I've written a couple articles for TidBITS since they started using John Gruber's Markdown format, and despite actually liking HTML as a writing format, I was impressed with Markdown's simplicity and efficiency (no <p>s are a big time savings!).

So I installed PHP Markdown Extra here on Extra Pepperoni, and got hooked on writing in Markdown. Unfortunately, there's no Markdown plug-in for plain Apache -- lots of ways to parse Markdown in your blogging software or wiki or CMS, but I want to be able to write a .text file and serve it up 'directly' from Apache on www.reppep.com.

Markdown is designed to run as a simple filter, so it's well suited to drop-in installation in a lot of places, without having to build customized versions for a particular application's APIs. There are several implementations -- the original Perl script, as well as versions in PHP (which I use in WordPress, slightly hacked), Python, Ruby, JavaScript, etc. http://markdown.infogami.com/ keeps a list.

Since I couldn't find an Apache handler (plug-in) or a CGI for Markdown, I wrote a very simple wrapper for Gruber's Markdown.pl. Conceptually, my wrapper spits out an HTML header, uses Markdown.pl to render the requested page as (X)HTML, and then appends an (X)HTML footer. The reality is slightly more complicated, due to the vagaries of figuring out the document's title, and conditionally inserting it back into the output as an <H1> tag. Even so, the whole thing is under 60 lines, mostly whitespace and comments.

Markdown.cgi also solves a problem which has wasted a significant amount of my time. BBEdit's built-in Preview tool can use Markdown.pl to generate HTML, which it then passes to WebKit for previewing in a formatted window. But if you put the pages on a real active website, BBEdit has another feature I really like, whereby it will actually calculate a live URL for the page to be previewed, request that URL from the web server, and preview that instead.

This is great, but if you're writing Markdown, BBEdit shows you the unrendered Markdown code (as served up by the web server), instead of rendering the Markdown file from disk. To make matters worse, BBEdit's Preview is live in real time, but continuously re-rendering a Markdown document as you type makes BBEdit stall badly on my 1.5GHz PBG4, so I've stopped using it as a live preview. I instead trained myself to use Markdown.pl as a UNIX script, which I manually trigger to generate a temporary HTML document. I then view this document in BBEdit's live Preview. Among other things, I frequently found myself editing the scratch HTML document, and having to copy my changes back to the Markdown source. Yuck.

Now that my web servers can serve up Markdown .text documents in HTML format, I can skip that whole mess, and go back to previewing .text documents (using Safari or BBEdit's live Preview) with server-side HTML conversion, seeing exactly what surfers see, as Siegel intended.

Tip: If you're reading about or trying out Markdown, don't read the syntax page -- skip to the simple crib sheet on the Dingus page. It's much simpler (and shorter!).

To implement this, I added some lines to my Apache httpd (1.3) configuration, inside the main vhost block: