Showdown's Markdown syntax

Introduction

Showdown was created by John Fraser as a direct port of the original parser written by markdown's creator, John Gruber. Although Showdown has evolved since its inception, in "vanilla mode", it tries to follow the original markdown spec (henceforth refereed as vanilla) as much as possible. There are, however, a few important differences, mainly due to inconsistencies in the original spec, which we addressed following the author's advice as stated in the markdown's "official" newsletter.

Showdown also support "extra" syntax not defined in the original spec as opt-in features. This means new syntax elements are not enabled by default and require users to enable them through options.

This document provides a quick description the syntax supported and the differences in output from the original markdown.pl implementation.

Paragraphs

Paragraphs in Markdown are just one or more lines of consecutive text followed by one or more blank lines.

On July 2, an alien mothership entered Earth's orbit and deployed several dozen 
saucer-shaped "destroyer" spacecraft, each 15 miles (24 km) wide.
    
On July 3, the Black Knights, a squadron of Marine Corps F/A-18 Hornets, 
participated in an assault on a destroyer near the city of Los Angeles.

Headings

You can create a heading by adding one or more # symbols before your heading text. The number of # you use will determine the size of the heading. This is similar to atx style.

# The largest heading (an <h1> tag)
## The second largest heading (an <h2> tag)
…
###### The 6th largest heading (an <h6> tag)

You can also use setext style headings.

This is an H1
=============
    
This is an H2
-------------

Note:
In live preview editors, when a paragraph is followed by a list it can cause an awkward effect.

You can prevent this by enabling the option "smoothPreview".

Blockquotes

You can indicate blockquotes with a >.

In the words of Abraham Lincoln:
    
> Pardon my french

Blockquotes can have multiple paragraphs and can have other block elements inside.

> A paragraph of text
>
> Another paragraph
>
> - A list
> - with items

Known differences and Gotchas

In most cases, Showdown's output is identical to that of Perl Markdown v1.0.2b7. What follows is a list of all known deviations. Please file an issue if you find more.

• This release uses the HTML parser from Markdown 1.0.2b2, which means it fails Inline HTML (Advanced).text from the Markdown test suite:

  <div>
  <div>
  unindented == broken
  </div>
  </div>
  

• Showdown doesn't support the markdown="1" attribute:

  <div markdown="1">
       Markdown does *not* work in here.
  </div>
  

• You can only nest square brackets in link titles to a depth of two levels:

  [[fine]](http://www.attacklab.net/)
  [[[broken]]](http://www.attacklab.net/)
  

  If you need more, you can escape them with backslashes.

• A list is single paragraph if it has only 1 line-break separating items and it becomes multi paragraph if ANY of its items is separated by 2 line-breaks:

 - foo

 - bar
 - baz

becomes

<ul>
  <li><p>foo</p></li>
  <li><p>bar</p></li>
  <li><p>baz</p></li>
</ul>

This new ruleset is based on the comments of Markdown's author John Gruber in the [Markdown discussion list][md-newsletter].

• Markdown.pl creates empty title attributes for inline-style images:

  Here's an empty title on an inline-style
  ![image](http://w3.org/Icons/valid-xhtml10).
  

  Showdown doesn't

• With crazy input, Markdown will mistakenly put <strong> or <em> tags in URLs:

  <a href="<*Markdown adds em tags in here*>">
     improbable URL
  </a>
  

  Showdown won't. But still, don't do that.