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.


Unknown said...

Could you elaborate on the warning about CGI? I am interested in this sort of markdown serving facility, but I am not familiar with the ancient CGI deities. Spell it out for us, please.

tony t said...

By wrath I mean, you could easily run into a resource exhaustion problem if you needed to render every single page for a popular site with a CGI script. There's no opcode cache, there's no results cached, it forks a new subprocess each time it's called, etc. etc. It's pretty inefficient and possibly even dangerous e.g. could crash your server.

Take a look at the latest version of the CGI that I've created: http://blog.tonns.org/2014/04/enabling-markdown-on-your-apache.html In that version I've enabled results caching to memcached. This will do a great deal to speed things up. Still, there are may be other avenues for resource exhaustion still available. I haven't thoroughly tested this out as I'm using internally only.

Ratings and Recommendations by outbrain