README.markdown

Render Markdown as HTML

This script was created to convert Markdown files to usable HTML on-the-fly on various web sites I deal with. It's intended for situations where the web server will be serving out Markdown files directly. It wasn't meant to be used with blogging or CMS tools. There are usually plug-ins for that.

By combining this with Apache's "Fancy Indexing" and WebDAV, you can throw together a quick and dirty documentation repository, for instance. Or maybe you just want to quickly share a document with someone on an existing web server without worrying about whether or not they've heard of Markdown.

Features

Generates a clickable table of contents (hidden by default) based on any headings found in the file.

Provides a link that will display the original text version of the document.

Metadata support (see below)

A mostly self-explanatory INI file is included to control behavior.

Syntax highlighting in <pre> blocks using Pygments (Python only)

Metadata

MultiMarkdown metadata can be ignored, removed, or displayed in a table. The table has an ID and it's parts have classes, so you can more easily target it in your CSS.

If you choose to display metadata in a table, you can optionally have certain values in the table turned into links. For instance, say you have all your documents indexed somehow by a metadata attribute called "tags" and your site will list matching documents at a URL like "http://www.mysite.tld/tags/foo". To make the displayed tags link to the appropriate address, you could define this in the INI:

link_attrs[] = "tags"
link_pattern = "http://www.mysite.tld/%k/%v"

link_attrs is an array of possible attribute names, so be sure to include the empty trailing brackets.

Requirements

Apache with mod_rewrite (This could surely be made to work with other web servers. If anyone does so, please let me know what it takes so I can include the instructions here.)

Setup

PHP

Download PHP Markdown (or PHP Markdown Extra) and PHP SmartyPants from Michel Fortin. Put markdown.php and smartypants.php somewhere in PHP's include path (or in the same directory as render.php).

Add an alias in your Apache config:

Alias /markdown/ "/var/www/support/markdown/"

Add rewrite rules. This can be done in the .htaccess file for a specific folder, or in the global Apache config. Some common extensions are included, but you can adjust them to your needs. (You might want to process all text as Markdown by adding "txt".)

Add rewrite rules. This can be done in the .htaccess file for a specific folder, or in the global Apache config. Some common extensions are included, but you can adjust them to your needs. (You might want to process all text as Markdown by adding "txt".)

Cautions

If you enable this globally for every directory on your web server and you use WebDAV, be sure to disable Apache's RewriteEngine on WebDAV folders or the Markdown files in your WebDAV volume will get sent to your file manager as HTML as well.

mod_userdir locations like http://server.tld/~user/Foo.mdown don't currently work. (It's difficult to determine the filesystem path using only the URL in such cases.)