Skip to content

Showdown's Markdown syntax

Jump to bottom
Estevão Soares dos Santos edited this page Dec 29, 2015 · 32 revisions

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.

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

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

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

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.

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

Colons can be used to align columns.

Keep in mind that, contrary to GFM, the outer pipes (|) are NOT optional. But you you don't need to make the raw Markdown line up prettily.

You can also use other markdown syntax inside them.

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.

Clone this wiki locally