Markdown & PHP

[John Gruber]

Jacob Patton <shotwise at yahoo.com> wrote on 03/16/04 at 8:05a:

> I'd like to use Markdown to help streamline my
> nonprofit org's PHP/MySQL CMS, but I'm not familiar
> enough with Perl to get it running with PHP.
> 
> How can I convert Markdown-formatted text to marked-up
> text via PHP (er, a PHP call to the Perl script,
> maybe?)?  I think this is what the Dingus does, but I
> can't figure out how to pull it off.

That's exactly what the Dingus does. 

I wrote a simple PHP wrapper for Markdown, which I named "PHP_MarkdownWrapper.php.inc". Here's the entire code:

    <?php
    
    include("markdown.config.inc");
    
    function convert_markdown ($input) {
        global $markdown_script;
        $input = escapeshellarg($input);
        return shell_exec("echo $input | $markdown_script");
    }
    
    function convert_smartypants ($input) {
        global $smartypants_script;
        $input = escapeshellarg($input);
        return shell_exec("echo $input | $smartypants_script");
    }
    
    function get_markdown_version () {
        global $markdown_script;
        return shell_exec("$markdown_script --shortversion");
    }
    
    function get_smartypants_version () {
        global $smartypants_script;
        return shell_exec("$smartypants_script --shortversion");
    }
    
    ?>


"markdown.config.inc" is another include file, saved in the same
folder as "PHP_MarkdownWrapper.php.inc". It contains two config
variables, which store the paths to your Markdown.pl and
SmartyPants.pl scripts. (You can ignore the SmartyPants stuff if you
just want Markdown by itself.)

    <?php
    $markdown_script    = "/full/path/to/Markdown.pl";
    $smartypants_script = "/full/path/to/SmartyPants.pl";
    ?>


Thus, I can include "PHP_MarkdownWrapper.php.inc" in any of my PHP
files, and do something like this to process Markdown:

    $markdown_str = "This is *Markdown*.";
    echo convert_markdown($markdown_str);

Or, if I want both SmartyPants and Markdown processing:

    echo convert_smartypants( convert_markdown($markdown_str) );

* * *

In fact, I'm using this trick for each of the pages in the
/projects/markdown/ section -- the text is written as Markdown,
saved as "filename.text", but each page is saved as a PHP wrapper
named "filename.php".

So I've got 10 files in /markdown/:

    basics.php
    basics.text
    dingus.php
    dingus.text
    index.php
    index.text
    license.php
    license.text
    syntax.php
    syntax.text

The PHP files contain all the HTML wrapper tags -- DOCTYPE, headers,
style sheet references, and a few divs in the body for the basic
structure of the page.

Then, in the body, where I want the actual text content to appear, I
have this:

    <div class="article">
    <?php
        $fname = $_SERVER['SCRIPT_FILENAME'];
        # turn '/blah/foo.bar' into '/blah/foo.text':
        $fname = preg_replace("@(.+)\.\w*$@", "$1.text", $fname);
        $fhandle = fopen($fname, 'r') or die($php_errormsg);
        $markdown_str = fread($fhandle, filesize($fname));
        fclose($fhandle) or die($php_errormsg);
        echo convert_smartypants( convert_markdown($markdown_str) );
    ?>
    </div> <!-- article -->

Which basically does the following:

1.  Get the current filename, store it in $fname
2.  Change $fname's '.php' extension to '.text'
3.  Try to open $fname and read the contents into $markdown_str
4.  Close $fname
5.  Convert $markdown_str to HTML and print it out

* * *

In theory, calling out to Perl like this puts a bit of overhead on
your PHP.  Each time I call convert_markdown() or
convert_smartypants(), my server needs to launch a separate Perl
process. If you're religious about "pure PHP", or "pure
whateverYourFavoriteScriptingLanguageIs" solutions, you're not going
to like this solution.

In practice, however, at least on my server, this overhead is
neglible. It feels instantaneous to me -- mostly because Markdown.pl
and SmartyPants.pl tend to run pretty quickly.

I hope this helps.

-- 
John Gruber          |              Daring Fireball
gruber at fedora.net    |    http://daringfireball.net