This is a card in Dave's Virtual Box of Cards.

Serving Local Markdown with PHP

Page created: 2025-08-12

I’ve got a bunch of projects with README.md files. (I standardized on Markdown when I made RepoRat to self-host all of my repos.)

I haven’t had a convenient way to preview my READMEs, which has been pretty annoying.

Tonight’s hack is serve-md.php. Entire source code below.

To be clear, what I’ve built here is a way to navigate to Markdown files and view them as rendered by an external markdown executable such as Discount (portland.or.us).

When I first visit it on my home web server, it presents all of the markdown files (must end in .md) in a path:

Screenshot of web page with links to markdown files.

Click one, and there it is:

Screenshot of a rendered markdown document in a web page.

Source

There’s the entirety of serve-md.php. Obviously, you’ll need to customize the path and possibly the Markdown to HTML renderer. (I use Discount’s markdown, which I picked when I made RepoRat.)

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Serve Markdown</title>
<style>
    body{ background: #fdf4db; margin:40px auto;
          max-width:700px; line-height:1.6; font-size:18px; }
    .md { background: #fff; font-size: .9em;
          border: 1px solid #000; padding: 1em; }
</style>
</head>
<body>
<?php
$path = "/home/dave/proj/";
if(isset($_REQUEST['f'])){
    $file = $path . $_REQUEST['f'];
    echo "<a href=\"?\">&lt;Back</a> - ";
    echo "<code>$file</code><br>\n";
    echo "<hr>\n";
    $html = shell_exec("markdown $file");
    echo "<div class=\"md\">$html</div>";
}
else{
	echo "<h1>Pick a Markdown File</h1>";
    $rdi = new RecursiveDirectoryIterator($path);
    foreach(new RecursiveIteratorIterator($rdi) as $file) {
        $short = str_replace($path, '', $file);
        if(preg_match('/\.md$/', $short)){
            echo "<a href=\"?f=$short\">$short</a><br>\n";
        }
    }
}
?>
</body></html>