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 Showdown 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.

The implication of the “one or more consecutive lines of text” is that Showdown supports “hard-wrapped” text paragraphs. This means the following examples produce the same output:

A very long line of text

A very
long line
of text

If you DO want to add soft line breaks (which translate to <br> in HTML) to a paragraph, you can do so by adding to space characters to the end of the line ( ).

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
-------------

Showdown generates bookmarks anchors in titles automatically, by adding an id property to an heading. This behavior can be modified or disabled with options. See the option section in the README.md file for more information.

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

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

Bold and Italic

You can make text bold or italic.

*This text will be italic*
**This text will be bold**

Both bold and italic can use either a * or an _ around the text for styling. This allows you to combine both bold and italic if needed.

**Everyone _must_ attend the meeting at 5 o'clock today.**

Strikethrough

With the option "strikethrough" enabled, Showdown supports strikethrough elements. The syntax is the same as GFM, that is, by adding two tilde (~~) characters around a word or groups of words.

a ~~strikethrough~~ element

Lists

Unordered lists

You can make an unordered list by preceding list items with either a * or a -.

* Item
* Item
* Item

- Item
- Item
- Item

Ordered lists

You can make an ordered list by preceding list items with a number.

1. Item 1
2. Item 2
3. Item 3

Nested lists

You can create nested lists by indenting list items by three* spaces.

1. Item 1
   1. A corollary to the above item.
   2. Yet another point to consider.
2. Item 2
   * A corollary that does not need to be ordered.
   * This is indented four spaces, because it's two spaces further than the item above.
   * You might want to consider making a new list.
3. Item 3

Code formatting

Inline formats

Use single backticks (`) to format text in a special monospace format. Everything within the backticks appear as-is, with no other special formatting.

Here's an idea: why don't we take `SuperiorProject` and turn it into `**Reasonable**Project`.

Multiple lines

To create blocks of code you should indent it by four spaces.

    this is a piece
    of
    code

If the options ghCodeBlocks is activated (which is by default), you can use triple backticks (```) to format text as its own distinct block.

Check out this neat program I wrote:

```
x = 0
x = 2 + 2
what is x
```

Links

Simple

If you wrap a valid URL or email in <> it will be turned into a link whose text is the link itself.

link to <http://www.google.com/>

this is my email <[email protected]>

In the case of email addreses, Showdown will also perform a bit of randomized decimal and hex entity-encoding to help obscure your address from address-harvesting spambots

With the option "simplifiedAutoLink" enabled, Showdown will turn every valid URL it finds in the text body to links automatically for you, without the need to wrap them in <>.

link to http://www.google.com/

this is my email [email protected]

Inline

You can create an inline link by wrapping link text in brackets ( [ ] ), and then wrapping the link in parentheses ( ( ) ).

For example, to create a hyperlink to github.com/showdownjs/showdown, with a link text that says, Get Showdown!, you'd write this in Markdown: [Get Showdown!](https://github.com/showdownjs/showdown).

Reference Style

You can also use the reference style, like this:

this is a [link to google][1]

some other text

[1]: www.google.com

Images

Markdown uses an image syntax that is intended to resemble the syntax for links, also allowing for two styles: inline and reference.

Inline

Inline image syntax looks like this:

![Alt text](/path/to/img.jpg)

![Alt text](/path/to/img.jpg "Optional title")

That is:

An exclamation mark: !;
followed by a set of square brackets, containing the alt attribute text for the image;
followed by a set of parentheses, containing the URL or path to the image, and an optional title attribute enclosed in double or single quotes.

Reference Style

Reference-style image syntax looks like this:

![Alt text][id]

Where “id” is the name of a defined image reference. Image references are defined using syntax identical to link references:

[id]: url/to/image  "Optional title attribute"

Image dimensions

When the option parseImgDimensionis activated, you can also define the image dimensions, like this:

![Alt text](/path/to/img.jpg=250x250 "Optional title")

Tables

Tables aren't part of the core Markdown spec, but they are part of GFM and Showdown supports them by turning on the option tables.

Colons can be used to align columns.

In the new version, the outer pipes (|) are optional, matching GFM spec.

You also don't need to make the raw Markdown line up prettily.

You can also use other markdown syntax inside them.

| Tables        | Are           | Cool  |
| ------------- |:-------------:| -----:|
| **col 3 is**  | right-aligned | $1600 |
| col 2 is      | *centered*    |   $12 |
| zebra stripes | ~~are neat~~  |    $1 |

Escaping markdown entities

Showdown allows you to use backslash (\) escapes to generate literal characters which would otherwise have special meaning in markdown’s syntax. For example, if you wanted to surround a word with literal underscores (instead of an HTML <em> tag), you can use backslashes before the unserscores, like this:

\_literal underscores\_

Showdown provides backslash escapes for the following characters:

\   backslash
`   backtick
*   asterisk
_   underscore
{}  curly braces
[]  square brackets
()  parentheses
#   hash mark
+   plus sign
-   minus sign (hyphen)
.   dot
!   exclamation mark

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.

Showdown doesn't support the markdown="1" attribute:
```
<div markdown="1">
     Markdown does *not* work in here.
</div>
```
A fix for this is currently under works
You can only nest square brackets in link titles to a depth of two levels:
```
[[fine]](http://www.github.com/)
[[[broken]]](http://www.github.com/)
```
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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Showdown's Markdown syntax

Introduction

Paragraphs

Headings

Blockquotes

Bold and Italic

Strikethrough

Lists

Unordered lists

Ordered lists

Nested lists

Code formatting

Inline formats

Multiple lines

Links

Simple

Inline

Reference Style

Images

Inline

Reference Style

Image dimensions

Tables

Escaping markdown entities

Known differences and Gotchas

Clone this wiki locally