Serving Markdown Direct from Apache

Friday, 13th May 2022

The popularity of static site generators tells me that a lot of people want to just write markdown and serve the resulting HTML directly from their webserver.

Does that describe you? Well put that bloated site generator down! Because Apache will happily serve your markdown as HTML - on demand - without the need to fill your harddrive with a static site generator and its thousands of outdated NPM dependencies.

Just enable the ext_filter module:

sudo a2enmod ext_filter

Install a markdown to HTML conversion tool:

sudo apt-get install markdown

And add a new output filter to your site config:

ExtFilterDefine md-to-html mode=output \
    intype=text/markdown outtype=text/html \
    cmd="/usr/bin/markdown"

<Directory /var/www/html>
    SetOutputFilter md-to-html
    AddType text/markdown .md
</Directory>

Now you can drop .md files directly into your server's DocumentRoot and visit them in your browser to see the HTML!

Taking this too seriously

This is just meant to be a bit of fun - but if you do want to try this in production, I suggest you cache the generated HTML. The conversion is usually very fast, but caching means Apache won't have to start a markdown process for each request.

Enable Apache caching modules:

sudo a2enmod cache
sudo a2enmod cache_socache
sudo a2enmod socache_shmcb

Add caching to the site config:

CacheSocache shmcb
CacheSocacheMaxSize 102400
CacheEnable socache /

This should give you performance plenty good enough for a personal site.

You probably also want to swap /usr/bin/markdown for a script that outputs a complete HTML document (including a <title> etc.). You might find Pandoc with the --standalone flag can help with that, but I'm leaving it as an exercise for you, dear reader.

Have fun playing with Apache - it can really do a lot of stuff! Try adding server-side includes for the full site-generator experience.