Adding Custom Tags to Markdown Plugin

From it's website, "Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)". This is accomplished by a number of impressive regular expressions which substitute the Markdown syntax with tags. As an example, this text in the Entry Editor:

#Heading One

Is reformatted when the entry is published, to:

<H1>Heading One</H1>

Brilliant! So it didn't take long before I had to see if Markdown could be leveraged to handle custom syntax for my own defined style blocks. A quick review of the Markdown plugin code confirmed my hopes and in less than an hour I had two working custom Markdown tags.

The tags I added were inspired by the "Note" and "Warning" text blocks which are popular on many Wiki sites. They're great for drawing the readers attention to necessary information amidst the rest of an article's text.

The first step was to choose the Markdown syntax I wanted to represent each style block. Obviously, I needed something that would work with the plugin's default syntax, but I also wanted something easy to remember. I ultimately chose ~! for the Warning style and ~? for the Note style. I really didn't have a scientific process for determining my choices (and they may change if I find conflicts in the future) but in my mind an exclamation point certainly relates to a warning, as a question mark denotes a thought or note.

Implementing the two new custom tags only required the modification of two files; Markdown.pl and screen.css.

First, I created a new subroutine in Markdown.pl called _DoNotesAndWarnings, which will handle the conversion of my custom syntax:

sub _DoNotesAndWarnings {
    my $text = shift;

    $text =~ s{
            \n~([\!\?])      # $1 = style class
            (.+?)           # $2 = Block text
            ~[\!\?]         # closing syntax
        }{
            my $style = ($1 eq '!') ? "Warning" : "Note";
            "<div class=\"$style\">" .  _RunSpanGamut("<b>$style:</b> \n" . $2)  .  "</div>\n\n";
        }egsx;

    return $text;
}

Next, I modified the _RunBlockGamut() subroutine to add a call to my new subroutine and I also added a second call to _HashHTMLBlocks(). This is so <p> tags aren't wrapped around my <div> blocks.

$text = _HashHTMLBlocks($text);

$text = _DoNotesAndWarnings($text);
$text = _HashHTMLBlocks($text);

$text = _FormParagraphs($text);

return $text;
}

The last step is to add the style definitions to the Cascading Style Sheet:

.Warning {
    width: 90%;
    margin-left: 5%;
    padding: .2em .3em;
    background: #F7CBCA;
    color: #000000;
    border: solid 1px #CC0000;
    font-size: 100%;
}

.Note {
    width: 90%;
    margin-left: 5%;
    padding: .2em .3em;
    background: #C9FFCA;
    color: #000000;
    border: solid 1px #349534;
    font-size: 100%;
}

Now to test the new custom Markdown tags I use the defined syntax in an entry:

~? This is a Note Block ~?

~! This is a Warning Block ~!

Which produces:

and...

However, those are just simple single line examples but multi-line input is handled just as well so we can do things like this:

~? This is a multi-line example.
<br/><br/>
`with an embedded code block` ~?

Will produce:

So there you have it! My Note and Warning custom Markdown tags are just two simple examples that show the flexibility of the Markdown plugin. Kudos to John Gruber and his development team!