Enabling Markdown on your apache webserver - update 3

Last time on "Enabling Markdown on your apache webserver":
And now, the exciting conclusion....

I've updated my CGI handler yet again with a few new features and I've posted it on my GitHub account, in the docs-on-clearance repo (get 'em cheap while they're all marked down! yuk yuk yuk). The new features are:

1. Included an Apache config snippet that you can just drop into an include directory.

2. The rendered HTML now has a stylesheet! And not just any stylesheet - a cool responsive Bootstrap stylesheet loaded from a CDN! Yes, it's mostly the plain default one with some margins, but it looks a lot better.

3. I enabled table-of-contents links for all header sections so you can have URI fragments that point directly to sections of your document. I consider this unfinished as the fragments are of the form #toc_2 - which isn't very useful. I believe the latest versions of the gem have GitHub style toc fragments, but that's not what is in the ubuntu package repos.

4. I've added support for caching the rendered HTML with memcached. This is more like a nice-to-have, but since we're going to use this full-time for internal documentation at $WORK, I figured I should make the extra effort. Of course, I chose poorly an outdated gem to implement this with, but it's ship now, fix later. Updating to Dalli or something on the ToDo list.

tl;dr - see the docs-on-clearance repo for the code.

As always, I welcome comments, suggestions and pull requests.


Building Icinga on Amazon Linux

As part of a datacenter to cloud migration for $WORK I recently needed to move our Icinga install to AWS. However, there is no current Icinga package for Amazon Linux. There exists a set of rpms when using rpmforge, but Amazon Linux is already setup for EPEL instead. The way forward? Build the rpms.

It actually wasn't very hard at all. I spun up a builder instance, built the rpms, copied them to an S3 bucket and then installed them on a fresh instance. Here's the steps:

1. prep the builder instance as root, getting all the dependencies installed.

yum -y --enablerepo=epel install fedora-packager rpmdevtools
yum -y --enablerepo=epel install gcc gd-devel zlib-devel libpng-devel libjpeg-devel libdbi-devel perl-ExtUtils-Embed
yum -y --enablerepo=epel install httpd-devel php php-devel php-gd php-ldap php-pdo php-xml php-pear
useradd makerpm

2. Never build an rpm as root. Use the "makerpm" user:

sudo su - makerpm
cd rpmbuild/
cat > .rpmmacros << EOF
%_topdir      %(echo $HOME)/rpmbuild
%_smp_mflags  -j3
%__arch_install_post   /usr/lib/rpm/check-rpaths   /usr/lib/rpm/check-buildroot

3. Build icinga-core rpms:

sudo su - makerpm
cd rpmbuild/SOURCES/
wget https://github.com/Icinga/icinga-core/releases/download/v1.11.0/icinga-1.11.0.tar.gz
tar zxvf icinga-1.11.0.tar.gz icinga-1.11.0/icinga.spec
mv icinga-1.11.0/icinga.spec ../SPECS/
rmdir icinga-1.11.0
cd ..
rpmbuild -ba --define="_vendor redhat" SPECS/icinga.spec

4. Build icinga-web rpms:

sudo su - makerpm
cd rpmbuild/SOURCES/
wget https://github.com/Icinga/icinga-web/releases/download/v1.11.0/icinga-web-1.11.0.tar.gz
tar zxvf icinga-web-1.11.0.tar.gz icinga-web-1.11.0/icinga-web.spec
mv icinga-web-1.11.0/icinga-web.spec ../SPECS/
rmdir icinga-web-1.11.0
cd ..
rpmbuild -ba --define="_vendor redhat" SPECS/icinga-web.spec

This process leans heavily on the Build Icinga RPMS page which is based on the How to create an RPM package page.


Enabling Markdown on your apache webserver - redux

In a previous post I enabled previewing of Markdown formatted documents using the Text::Markdown perl module. However simple that module was to implement, it only implemented daringfireball markdown. Things at $WORK have ramped up the adoption of Markdown and the atrophied standard is not enough. So, I've had to find another renderer.

Started by looking at how GitHub renders markdown and found they use the Redcarpet gem. The examples in the documentation combined with the ruby-redcarpet Ubuntu package make this a pretty simple exercise in upgrading my Markdown renderer:
  1. Install the Redcarpet gem:

  2. apt-get install ruby-redcarpet

  3. Replace ye olde Markdown.cgi with new hotness Markdown.cgi

  4. #!/usr/bin/ruby
    require 'redcarpet'
    print "Content-type: text/html\n\n"
    markdown = Redcarpet::Markdown.new(
        :autolink => true,
        :fenced_code_blocks => true,
    puts markdown.render(File.read(ENV['PATH_TRANSLATED']))

  5. Start your browser, surf the docs!
UPDATE: I've updated my renderer for Markdown.

Ratings and Recommendations by outbrain