Making Markdown to HTML Live Generated Webpages

This guide will show you how to produce simple static webpages using markdown, and have them live converted to html on the fly by your webserver using PHP.

Tools Used

Preparing The Environment

First make sure that PHP is set up correctly on your http server. I use Apache for this tutorial, but any PHP supporting http server will work as long as you change the rewrite rule to match that server's format.

Download Parsedown.php and ParsedownExtra.php and place them somewhere on the document root of your website.

Parsedown.php provides the main parser for Markdown syntax, while ParsedownExtra.php is an extension for Parsedown that provides support for the Markdown Extra syntax. While ParsedownExtra is not strictly necissary, I highly recommend it for the extra features Markdown Extra provides.

Adding The Rewrite Rule

If using Apache, make sure that you have the Rewrite module enabled, and then add these lines to your config file or htaccess file.

Options +FollowSymLinks
RewriteEngine On
RewriteRule ^(.*).md$ markdown.php?page=$1 [PT,L]

This rule matches any url ending in .md and replaces it with path to our markdown page generator, with the path to the markdown file as an argument.

This also works for index pages if you add something like index.md to your DirectoryIndex statement in your Apache config.

Setting Up The Page Framing

In order to make it easy and painless to integrate markdown pages into your website, we will set up an html page that provides the head section and some body content, and then calls the parser to fill out the rest of the page content from the markdown file.

First of all, since we are not actually going to navigate to the markdown pages, we need to manually add 404 handeling. We can accomplish this by adding a php block at the begining of the head section of our file that checking if the requested file exists, and returns a 404 header and includes the content of your 404 page. We include the 404 page rather than redirect to it because a 404 response should identify a page that does not exist, not a page that redirects to another page.

<?php
if (isset($_GET['page'])) { $page = $_GET['page']; }
    if (isset($page)) {
        if (!is_file($page.".md")) {
            header($_SERVER["SERVER_PROTOCOL"]." 404 Not Found" );
            include($_SERVER['DOCUMENT_ROOT']."/system_pages/404.php");
            exit();
        }
    }
?>

We will then add a block into the body of our html file that calls the parser to generate the formatted markdown page.

<?php
include($_SERVER['DOCUMENT_ROOT']."/system_pages/Parsedown.php");
include($_SERVER['DOCUMENT_ROOT']."/system_pages/ParsedownExtra.php");
if (isset($_GET['page'])) { $page = $_GET['page']; }
if (isset($page)) {
    print ParsedownExtra::instance()
    ->text(file_get_contents($page.".md"));
}
?>

Conclusion

This setup should allow you to quickly add new static pages to your website simply by placing the markdown files in the correct place in your websites directory structure.