Standard Flavored Markdown Tips

Today, some of the biggest users of Markdown have given a gift to the Internet: Standard Flavored Markdown (Read more in Jeff Atwood's Blog Post)

I played with it for an hour and I'm absolutely in love with it, for three reasons:

  1. It's rock solid and mature - Try nesting Ordered and Unordered Lists in any combination and see it just do the right thing, something many implementations struggle with
  2. It comes with a reference implementation in C and JavaScript
  3. The JavaScript implementation is easy to extend (I have not done anything with the C version)

I was able to replace the Markdown parser in our current application with the stmd.js reference parser and got up and running immediately.

Here are some tips:

The Parser and Renderer are two different things

Instead of just taking Markdown and giving you HTML, stmd.js consists of a separate Parser and Renderer. This is massively useful, because it means you can either massage the parsed markdown tree before you render it, but you can also impact how the Markdown is rendered without messing up the parsing code. Look at this example:

var parser = new stmd.DocParser();
var renderer = new stmd.HtmlRenderer();
var input = "this **is** a\r\n" +
            "test.\r\n\r\n" +
            "With Inline-<b>HTML</b> as well";

var ast = parser.parse(input);

var html = renderer.render(ast);

document.getElementById("output").innerHTML = html;

Set a breakpoint (with Firebug or whatever JavaScript debugger you use) and look at the glorious ast. Look at the collections of children, at the tokens, and then you might see why this is so great: You can monkey around with this, without having to worry about HTML rendering.

Treat newlines as linebreaks

This is possibly the #1 request people have when they first try out Markdown. Normally, you need to have two spaces at the end of the line to make it a newline, otherwise it's a space.

The parser correctly determines a simple newline as a Softbreak token. The default renderer renders Softbreaks as \n, that is a HTML newline which doesn't translate into an actual line break. This is trivial:

var renderer = new stmd.HtmlRenderer();
renderer.softbreak = "<br/>";

Now, every linebreak inserts a proper <br> tag.

Disallow all HTML

Markdown allows Inline-HTML, since the original audience were programmers/bloggers. However, in some environments it may be required to disable any and all inline-HTML. To disable all HTML parsing, we tell the Parser to not generate any Html tokens:

var parser = new stmd.DocParser();
parser.inlineParser.parseHtmlTag = function() { return 0; }

All HTML Tags will now be interpreted as Str tokens and thus escaped on rendering.

Read the Source Code

The Source is on GitHub, and I highly recommend reading through stmd.js to understand how it works and where the extensibility points are. I wish that the Parser and Renderer were in two separate files, but it's still very straight forward. Yes, there is a Regex which parses HTML, but since Markdown doesn't just support any HTML but rather a defined subset, this is fine.

You should almost never have to edit stmd.js directly. Monkey patch, yes. But that can be in your consumer code.

This library is a gift.

Thank you, Standard Flavored Markdown team.