2012-10-26

Enabling Markdown on your apache webserver

At $WORK, we're toying with moving all documentation with Markdown and git. To do that I needed to be able to render it locally to preview before pushing to GitHubBitbucket or another yet-to-be-determined repository. This setup was rather quick, easy and painless. Here's the steps:

1. Install Text::Markdown as your converter. The perl-Text-Markdown RPM was in the repoforge repository:

sudo yum install perl-Text-Markdown

2. The package comes with a script that does all the heavy lifting. It just needs to be slightly tweaked to make it run as a CGI.
$ cp -p /usr/bin/Markdown.pl $CGIBIN/Markdown.cgi
$ cd $CGIBIN
$ vi Markdown.cgi
$ diff -U0 /usr/bin/Markdown.pl Markdown.cgi
--- /usr/bin/Markdown.pl        2011-02-10 11:50:20.000000000 -0500
+++ Markdown.cgi        2012-10-26 12:08:53.000000000 -0400
@@ -147 +147,2 @@
-print main(@ARGV) unless caller();
+print "Content-type: text/html\n\n";
+print main($ENV{PATH_TRANSLATED}) unless caller();
3. Configure an apache handler to hand all Markdown-formatted files to your action.

Action markdown /cgi-bin/Markdown.cgi
AddHandler markdown .md

4. Gracefully restart apache

sudo apachectl graceful

Tips: This is for private previewing. Don't put this on your public webserver. If you do, you're asking for the wrath of the ancient CGI deities to descend upon your server and sunder it to ashes. If I was doing this for a public facing site, I'd use something that caches the opcode for the script (most likely in another programming language as well), caches the rendered page in memcache, etc. etc. You've been warned.

UPDATE: I've updated my renderer for Markdown.

Ratings and Recommendations by outbrain